Skip to Content
supedocs

HTTP API

Call supe from your own code with an API key.

The API is for programs: plain HTTP, stable error codes, and the same tools, rules and receipts as the CLI and MCP.

Base URLhttps://service.oex.sh/v1
AuthAuthorization: Bearer <key>
Contract/v1/openapi.json

Get a key

On the dashboard, open Agents → Get an API key → Make a key. You see the key once.

  • oex_live_... keys make real calls and spend credits.
  • oex_test_... keys return sample data and cost nothing. Use one while you wire things up.

Your first call

curl -s https://service.oex.sh/v1/run \
  -H "Authorization: Bearer $SUPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool": "frankfurter#rate", "input": {"path": {"from": "EUR", "to": "USD"}}}'
{
  "status": "succeeded",
  "tool_id": "frankfurter#rate",
  "tags": ["exchange_rate"],
  "data": { "date": "2026-11-17", "base": "EUR", "quote": "USD", "rate": 1.1033 },
  "results": 1,
  "cost": 0,
  "unit": "credits",
  "run_id": "run_c61f64885fcb",
  "test": false,
  "latency_ms": 66,
  "receipt_url": "https://app.oex.sh/activity/run_c61f64885fcb"
}

data is the provider's own response. cost is in credits (1,000 credits are $1).

Find the tool first

curl -s "https://service.oex.sh/v1/tools?query=exchange%20rates" -H "Authorization: Bearer $SUPE_API_KEY"
curl -s "https://service.oex.sh/v1/tools/frankfurter%23rate" -H "Authorization: Bearer $SUPE_API_KEY"

The first lists matching tools with their price and tags. The second gives one tool's parameters by part (path, query, body). Encode the # in a tool id as %23.

Retries

Send an Idempotency-Key header with any unique value. A retry with the same key and body returns the first answer instead of running again, for 24 hours, so a network blip never pays twice.

Every endpoint is in the HTTP API reference, and every error in Errors and exit codes.

On this page