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 URL | https://service.oex.sh/v1 |
| Auth | Authorization: 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.