API reference
Playground
Every endpoint in the read API, callable from this page. Requests go to https://api.roundhouseai.io/v0 — the same URL your code will use, on this origin, so nothing needs configuring first.
What this caller is entitled to, and what it would be charged
Who the credential in front of this request resolves to, which of the two paid lanes it would take, what it has left to spend, and the price of every route on both lanes. Unmetered and answerable WITHOUT a key: checking your balance must never cost a unit and must never be the thing that fails. A caller with no key gets a real answer (tier: anonymous, lane: x402, the full price list), not a 401, so both prices can be compared before committing to either. An unrecognised key also answers 200, with key_recognised: false — this is the endpoint you reach for when your key is the thing that is broken, so it must work then.
Sent as a bearer token, from your browser to this origin only. It is never recorded — not in analytics, not in session replay. The API is keyed: only the capability endpoints and the service directory answer without one.
/api/v0/accountcurl -sL "/api/v0/account"
Send a request to see the response.
Not callable from here
These need a signed payment, which this page deliberately does not hold a wallet for.
post/v0/mcp
Every endpoint in this document, as MCP tools, over stateless Streamable HTTP. POST one JSON-RPC 2.0 message per request: initialize, ping and tools/list need no key; a tools/call is forwarded to the endpoint the tool wraps and answered by that endpoint's own gate, so the key requirement, the rate limit and the Query Unit charge are identical to calling it directly. Versioned with the rest of this surface: MCP negotiates the wire protocol, not whether a tool still takes the arguments it takes today. There is no server-initiated SSE stream and no session id, so GET and DELETE answer 405.
get/v0/queries/{slug}/results
Executes a published saved query and returns its rows. Two ways to pay for one URL: attach an API key and the run is metered in Query Units against your organization, or attach nothing and it answers 402 with standard x402 requirements — settle that and the rows come back, with no account and no key. Only queries whose author has enabled agent calls are payable; the rest need a key. Declared parameters are passed in the query string and are validated BEFORE any payment is taken, so a bad value costs a 400 rather than a settlement.
get/v0/test/x402
A real paywalled resource. Called without payment it answers 402 with standard x402 requirements, which is the cheapest way to see a live challenge. Pay it and it mints a trial API key raising the SQL limit to 240 queries/minute for 30 days. It also advertises KYA and accepts a memo in X-PAYMENT-MEMO.
get/v0/topup
Self-serve Query Unit purchase for organization API keys. Send your org key and no payment and the answer is a 402 pricing the requested ?usd=; resend with X-PAYMENT and the settled USDC is credited to the key's organization at 200,000 QU per $1. One settlement credits exactly once — a replayed payment answers 409. Trial keys are refused: they hold no Query Unit balance. Card top-ups live in the dashboard at /dashboard/billing.
Walk one end to end in your first x402 payment.