HTTP API
The /v1 endpoints and what they return.
Base URL https://service.oex.sh/v1. Send Authorization: Bearer <key> on every request. The machine-readable contract is /v1/openapi.json. Amounts are in credits (1,000 credits are $1).
Endpoints
| Endpoint | What it does |
|---|---|
GET /v1/tags | Every tag, what it means, and how many tools you can use carry it |
GET /v1/tools?query=&tag=&provider=&max_price=&limit= | Tools, best first, with price and tags. 10 for a search; more counts the rest. |
GET /v1/tools/{id} | One tool: method, path, parameters by part (input), price, docs, and up to 5 alternatives. Encode # as %23. |
POST /v1/run | Run a tool |
GET /v1/jobs/{id}?wait= | Collect a long job |
POST /v1/runs | Open a run: {"goal", "budget"} |
GET /v1/runs, GET /v1/runs/{id} | Runs and their receipts |
POST /v1/files | {"name"} for a one-time upload_url, or {"url"} to store a copy of a link |
GET /v1/files?name= | Files in the workspace |
GET /v1/recipes?query=, GET /v1/recipes/{id}?tier=, POST /v1/recipes | Find, read and save recipes |
GET /v1/rentals, POST /v1/rentals/{id}/release | Rented numbers and inboxes |
GET /v1/wallet | balance, held, available |
GET /v1/me, PATCH /v1/me | The workspace and this agent; {"name"} renames the agent |
POST /v1/approvals | Ask a person: {"kind": "tool_access" or "budget", "tool_id", "reason", "amount"} |
POST /v1/run
{
"tool": "serper#search",
"input": { "body": { "q": "lighthouses", "num": 5 } },
"max_price": 10,
"run_id": "run_…",
"budget": 500,
"goal": "find lighthouse photos",
"confirmation": "act_…"
}| Field | |
|---|---|
tool | Required. An exact tool id. |
input | {path, query, body}, each with the tool's own parameter names in the part GET /v1/tools/{id} lists. Leave out parts the tool doesn't take. |
max_price | Refuse if the call costs more (402 price_above_max) |
run_id | Bill an open run. Without it, a run opens with budget (default 1,000) and goal. |
confirmation | Go ahead with a call that answered 409 needs_confirmation |
Answers
200:{status: "succeeded", tool_id, tags, data, results, cost, unit, run_id, test, latency_ms, receipt_url}.datais the provider's own response.202:{status: "running", job_id, run_id, elapsed_s, check_again_in_s, poll}for a job still going after about 45 seconds. Collect it withGET /v1/jobs/{id}?wait=20.- 4xx/5xx:
{"error": {"code", "message", "details"}}. Nothing is charged. See Errors.
A test key (oex_test_…) gets an empty answer of the tool's kind and test: true. Nothing is called or charged.
Idempotency-Key
Send any unique value as an Idempotency-Key header. A retry with the same key and body returns the first answer, with Idempotent-Replayed: true, for 24 hours. The same key with a different body is 422 idempotency_mismatch; one still in flight is 409 idempotency_in_progress.