Skip to Content
supedocs

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

EndpointWhat it does
GET /v1/tagsEvery 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/runRun a tool
GET /v1/jobs/{id}?wait=Collect a long job
POST /v1/runsOpen 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/recipesFind, read and save recipes
GET /v1/rentals, POST /v1/rentals/{id}/releaseRented numbers and inboxes
GET /v1/walletbalance, held, available
GET /v1/me, PATCH /v1/meThe workspace and this agent; {"name"} renames the agent
POST /v1/approvalsAsk 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
toolRequired. 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_priceRefuse if the call costs more (402 price_above_max)
run_idBill an open run. Without it, a run opens with budget (default 1,000) and goal.
confirmationGo 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}. data is 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 with GET /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.

On this page