{"openapi":"3.1.0","info":{"title":"OEX API","version":"2.0.0","description":"Discover, price and run services against one prepaid balance. Authenticate with an agent key from the OEX dashboard."},"servers":[{"url":"https://service.oex.sh"}],"security":[{"key":[]}],"paths":{"/v1/run":{"post":{"operationId":"run","summary":"Run one tool with its own parameters.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retries with the same key return the first answer instead of running again, for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequest"}}}},"responses":{"200":{"description":"It ran.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResult"}}}},"202":{"description":"A long job is under way; poll it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobRunning"}}}},"400":{"description":"Invalid request or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Money: a budget, limit, the balance, or max_price stopped it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A workspace rule stopped it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Needs confirmation, or the Idempotency-Key is in use.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The provider failed. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"No tool is set up for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The provider or job timed out. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/{job_id}":{"get":{"operationId":"getJob","summary":"Collect a long job.","parameters":[{"name":"job_id","in":"path","required":true,"description":"From a 202 answer.","schema":{"type":"string"}},{"name":"wait","in":"query","required":false,"description":"Seconds to wait for it to finish (default 20).","schema":{"type":"number","minimum":0,"maximum":45}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResult"}}}},"202":{"description":"Still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobRunning"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The provider failed. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The provider or job timed out. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tags":{"get":{"operationId":"listTags","summary":"Every tag, what it means, and how many tools carry it.","responses":{"200":{"description":"The tags.","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tools":{"get":{"operationId":"listTools","summary":"Tools for a job, best first (MCP's find_tool).","parameters":[{"name":"query","in":"query","required":false,"description":"Plain-language search.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Only tools with this tag.","schema":{"type":"string"}},{"name":"provider","in":"query","required":false,"description":"Only this provider's tools.","schema":{"type":"string"}},{"name":"max_price","in":"query","required":false,"description":"Price per call at most, in credits.","schema":{"type":"number"}},{"name":"limit","in":"query","required":false,"description":"How many tools to show; a search shows 10.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"The tools.","content":{"application/json":{"schema":{"type":"object","required":["tools","more"],"properties":{"query":{"type":"string"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}},"more":{"type":"integer","description":"Matching tools not shown."},"available":{"type":"number","description":"Credits: 1,000 credits are $1."},"unit":{"type":"string"},"switched_off":{"type":"array","items":{"type":"string"},"description":"Tools that match but are switched off for this key."},"hint":{"type":"string"}}}}}},"400":{"description":"Invalid request or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tools/{tool_id}":{"get":{"operationId":"getTool","summary":"One tool's full contract (MCP's inspect_tool).","parameters":[{"name":"tool_id","in":"path","required":true,"description":"URL-encoded, e.g. serpapi%23google","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolDetail"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/runs":{"post":{"operationId":"startRun","summary":"Open a run: one budget and one receipt for several calls.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"goal":{"type":"string"},"budget":{"type":"number","description":"Credits: 1,000 credits are $1.","minimum":0}}}}}},"responses":{"201":{"description":"The run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"400":{"description":"Invalid request or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listRuns","summary":"Recent runs, newest first.","parameters":[{"name":"limit","in":"query","required":false,"description":"How many (default 20).","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"The runs.","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/RunSummary"}}}}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/runs/{run_id}":{"get":{"operationId":"getRun","summary":"A run's receipt: every step and what it cost.","parameters":[{"name":"run_id","in":"path","required":true,"description":"From a run answer.","schema":{"type":"string"}}],"responses":{"200":{"description":"The receipt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/files":{"get":{"operationId":"listFiles","summary":"Files added to this workspace; with `name`, only that one.","parameters":[{"name":"name","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The files.","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createUploadLink","summary":"A one-time link to upload a local file to, or with `url` a stored copy of that link, for a tool that takes a link.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The file's name with its extension, e.g. 'car.jpg'. Required unless `url` is given."},"url":{"type":"string","description":"A public http(s) link to copy the file from, or a data: URI."}}}}}},"responses":{"200":{"description":"The link, or the stored copy.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UploadLink"},{"$ref":"#/components/schemas/File"}]}}}},"400":{"description":"Invalid request or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`fetch_failed`: the `url` timed out or couldn't be reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Upload links can't be signed on this server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/recipes":{"get":{"operationId":"findRecipes","summary":"Recipes for a job of more than one step, best first. With no query, the workspace's own.","parameters":[{"name":"query","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The recipes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"saveRecipe","summary":"Keep a recipe in the workspace: copy one from the Cookbook, or compose one from steps.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipe_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"inputs":{"type":"object","additionalProperties":true},"steps":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"responses":{"200":{"description":"The saved recipe.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/recipes/{recipe_id}":{"get":{"operationId":"getRecipe","summary":"One recipe to follow: its inputs and steps, and how to fill them.","parameters":[{"name":"recipe_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"tier","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The recipe.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/rentals":{"get":{"operationId":"listRentals","summary":"What this workspace rents by the month: its own phone numbers and email inboxes.","responses":{"200":{"description":"The rentals.","content":{"application/json":{"schema":{"type":"object","properties":{"rentals":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/rentals/{rental_id}/release":{"post":{"operationId":"releaseRental","summary":"Stop renewing a rental. It works until its paid_through date, then the provider releases it for good.","parameters":[{"name":"rental_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The rental.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A workspace rule stopped it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/wallet":{"get":{"operationId":"getWallet","summary":"The workspace's balance.","responses":{"200":{"description":"The balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wallet"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me":{"get":{"operationId":"getMe","summary":"Who is calling: the workspace, this agent and the limits on it.","responses":{"200":{"description":"The caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"renameMe","summary":"Name this agent as it connects (within 10 minutes of its first call), as people see it on the Agents page.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80}}}}}},"responses":{"200":{"description":"Renamed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"400":{"description":"Invalid request or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A workspace rule stopped it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/approvals":{"post":{"operationId":"requestApproval","summary":"Ask a person to switch a tool on or raise a limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","tool_id","reason"],"properties":{"kind":{"type":"string","enum":["tool_access","budget"]},"tool_id":{"type":"string"},"reason":{"type":"string"},"amount":{"type":"number","description":"Credits: 1,000 credits are $1.","minimum":0}}}}}},"responses":{"201":{"description":"Filed.","content":{"application/json":{"schema":{"type":"object","properties":{"approval_id":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"Invalid request or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"key":{"type":"http","scheme":"bearer","description":"oex_live_… or oex_test_… (sample data, free)."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["awaiting_signature","confirmation_changed","confirmation_invalid","fetch_failed","idempotency_in_progress","idempotency_mismatch","insufficient_balance","invalid_input","invalid_request","job_expired","limit_reached","name_locked","needs_confirmation","not_found","price_above_max","provider_error","provider_timeout","run_budget_exceeded","test_key","tool_disabled","tool_not_allowed","tool_not_compliant","tool_unavailable","unauthorized","unavailable","workspace_frozen"]},"message":{"type":"string","description":"What happened and what to do, in a sentence."},"details":{"type":"object","additionalProperties":true,"description":"The refusal's facts: reason, tool_id, run_id, needed, available, limit, and for needs_confirmation the preview (confirmation, will_do, price)."}}}}},"Input":{"type":"object","additionalProperties":false,"description":"The tool's parameters by the provider's own names, each in the part of the request it goes in, as GET /v1/tools/{tool_id} lists them. A parameter in the wrong part is refused with where it goes.","properties":{"path":{"type":"object","additionalProperties":true},"query":{"type":"object","additionalProperties":true},"body":{"type":"object","additionalProperties":true}}},"RunRequest":{"type":"object","required":["tool"],"properties":{"tool":{"type":"string","description":"The tool id, e.g. `serper#search`."},"input":{"$ref":"#/components/schemas/Input"},"run_id":{"type":"string","description":"Bill to this run. A new run is opened if omitted."},"budget":{"type":"number","minimum":0,"description":"Budget for the new run, in credits (1,000 credits = $1)."},"goal":{"type":"string","description":"What the new run is for."},"max_price":{"type":"number","minimum":0,"description":"Refuse the call if it costs more, in credits."},"confirmation":{"type":"string","description":"The id from a `needs_confirmation` preview, once agreed."}}},"RunResult":{"type":"object","required":["status","tool_id","data","cost","run_id"],"properties":{"status":{"type":"string","enum":["succeeded"]},"tool_id":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"data":{"description":"The provider's own response. For a tool OEX builds from several calls (`built_by_oex`), the fields its `output` lists."},"results":{"type":"integer","description":"How many results it counted, for a price per result."},"cost":{"type":"number","description":"What was charged, in credits."},"unit":{"type":"string","enum":["credits"]},"run_id":{"type":"string"},"job_id":{"type":"string"},"test":{"type":"boolean","description":"A test key: an empty answer, nothing called or charged."},"latency_ms":{"type":["integer","null"]},"receipt_url":{"type":["string","null"]},"attribution":{"type":"string","description":"The credit the provider's data licence requires shown with this answer."}}},"JobRunning":{"type":"object","required":["status","job_id"],"properties":{"status":{"type":"string","enum":["running"]},"job_id":{"type":"string"},"tool_id":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"run_id":{"type":"string"},"elapsed_s":{"type":"integer"},"check_again_in_s":{"type":"integer","description":"About when to poll again, in seconds."},"poll":{"type":"string","description":"GET this path to collect the result."}}},"Tag":{"type":"object","required":["name","summary","tools"],"properties":{"name":{"type":"string"},"summary":{"type":"string"},"tools":{"type":"integer","description":"How many tools this key can use carry it."}}},"Tool":{"description":"`price.amount` is in credits; `price.usd` is the provider's own price.","type":"object","required":["tool_id","provider","tags","price","usable"],"properties":{"tool_id":{"type":"string"},"provider":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"built_by_oex":{"type":"boolean","description":"OEX makes several provider calls and answers in its own `output` fields."},"summary":{"type":"string"},"price":{"type":"object","properties":{"type":{"type":"string","enum":["FREE","PER_CALL","PER_RESULT","METERED"]},"amount":{"type":"number","description":"Credits per call, per result, or per `unit` (METERED)."},"usd":{"type":"number","description":"The provider's own price, in dollars."},"unit":{"type":"string","description":"METERED only: what is measured, e.g. 'minute of audio'."},"max_per_call":{"type":"number","description":"METERED only: the most one call costs, in credits."},"summary":{"type":"string","description":"The price in words, e.g. '5 credits per call'."}}},"latency_ms":{"type":"object"},"consequence":{"type":"boolean","description":"Irreversible: needs confirmation."},"long_running":{"type":"boolean"},"usable":{"type":"boolean"},"unusable_reason":{"type":"string"},"pinned":{"type":"boolean"},"affordable":{"type":"boolean","description":"The available balance covers one call."}}},"ToolDetail":{"description":"A tool's full contract, and a few other tools sharing its tag.","allOf":[{"$ref":"#/components/schemas/Tool"},{"type":"object","properties":{"method":{"type":"string","description":"The provider endpoint this tool calls; absent for a built_by_oex tool, which takes its input in body."},"path":{"type":"string"},"input":{"type":"object","description":"Parameters by part: {path?, query?, body?}, each {name: {type, required, description, default, enum, …}}. A dotted body name nests; a `[]` is a list."},"returns":{"type":"string","enum":["list","object"]},"results_at":{"type":"string","description":"Where the results list is in the provider's answer."},"answer_at":{"type":"string","description":"Where the one result is in the provider's answer."},"output":{"type":"array","items":{"type":"string"},"description":"A built_by_oex tool's fields."},"docs":{"type":"string"},"configured":{"type":"boolean"},"alternatives":{"type":"array","items":{"$ref":"#/components/schemas/Tool"},"description":"Others sharing its first tag, cheapest first. Each takes its own parameters."},"more_alternatives":{"type":"integer"}}}]},"Run":{"type":"object","properties":{"run_id":{"type":"string"},"goal":{"type":"string"},"title":{"type":"string","description":"The goal, or for a run with no goal a name made from its first step."},"budget":{"type":"number","description":"Credits: 1,000 credits are $1."},"spent":{"type":"number","description":"Credits: 1,000 credits are $1."},"budget_left":{"type":"number","description":"Credits: 1,000 credits are $1."},"unit":{"type":"string","enum":["credits"]},"steps":{"type":"array","items":{"type":"object"}},"receipt_url":{"type":"string"}}},"RunSummary":{"type":"object","required":["run_id"],"properties":{"run_id":{"type":"string"},"goal":{"type":["string","null"]},"title":{"type":["string","null"]},"budget":{"type":["number","null"]},"spent":{"type":"number","description":"Credits: 1,000 credits are $1."},"steps":{"type":"integer","description":"How many steps ran."},"ok":{"type":"boolean"},"created_at":{"type":"number"},"running":{"type":"boolean"}}},"File":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string"},"type":{"type":"string"},"size":{"type":"integer"},"url":{"type":"string"},"uploaded_at":{"type":"string"},"size_display":{"type":"string"}}},"UploadLink":{"type":"object","required":["upload_url","expires_in_s","max_bytes"],"properties":{"upload_url":{"type":"string","description":"PUT the file here, once. The answer is the stored file, with its `url`."},"expires_in_s":{"type":"integer"},"max_bytes":{"type":"integer"}}},"Wallet":{"type":"object","properties":{"balance":{"type":"number","description":"Credits: 1,000 credits are $1."},"held":{"type":"number","description":"Credits: 1,000 credits are $1."},"available":{"type":"number","description":"Credits: 1,000 credits are $1."},"unit":{"type":"string","enum":["credits"]},"test":{"type":"boolean"}}},"Me":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"agent":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"limits":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","enum":["call","day","month","total"]},"limit":{"type":"number","description":"Credits: 1,000 credits are $1."},"spent":{"type":"number","description":"Credits: 1,000 credits are $1."}}}},"unit":{"type":"string","enum":["credits"]},"test":{"type":"boolean"}}}}}}