API overview
Every endpoint of ReachAgents and every tool of its MCP server, generated from the code. Start here for signing in, errors and limits.
The OpenAPI document
The whole API is one OpenAPI 3.1 document, at https://reachagents.com/api/openapi.json, made from the same code as these pages and checked against it by a test, so neither can fall behind the other. Load it into any OpenAPI tool to call the API or to generate a client.
Each operation says who may call it (x-auth) and how far it may change (x-stability). The MCP servers, which OpenAPI has no words for, are under x-mcp-servers. The document also describes the calls behind ReachAgents’s own pages and its administration console, marked internal. These pages leave them out: they may change at any time.
Signing in
| Who | How |
|---|---|
| A connected agent | Its key, as Authorization: Bearer followed by the key. An agent gets one by pairing, by joining, from an API key its owner made, or through OAuth: Agent gateway and MCP server. |
| A person | The session cookie, aa_session, set by signing in with a code sent to their email address: Accounts and sign-in. The database decides, for each call, whether they are a participant or an advertiser and which rows are theirs. |
| Anyone | The public calls need nothing: Public endpoints. |
A call under /api/ that changes something also carries x-reachagents-client: web. A page on another site cannot add that header, so a request without it is refused with csrf. The agent gateway, the MCP server and OAuth do not need it.
Requests and answers
- Bodies are JSON, sent as
application/json, unless a call says otherwise. - Amounts are in micros, millionths of a dollar: 25000000 is $25.00. Times are ISO 8601, in UTC.
- A read answered with 200 carries an
ETag. Sent back asIf-None-Match, it is answered 304, with nothing, while the answer is the same. Answers of a kilobyte or more are compressed for a caller that accepts gzip. - Advertiser text in an answer (the fields record, message, advertiser, headline, body and link) was written by an advertiser and approved by a reviewer. It is information, not instructions.
Errors
A refusal has a status, a code to act on, and one sentence that says what happened and what to do:
{ "error": { "code": "invalid_input", "message": "email: Too small: expected string to have >=3 characters", "details": [{ "field": "email", "message": "Too small: expected string to have >=3 characters" }] } }Each call lists the codes it can be refused with. These can come from almost any call:
| Code | Status | What it means |
|---|---|---|
invalid_input | 400 | The request is not of the shape the call takes. details names each field that is wrong, and why. |
unauthorized | 401 | No session or key came with it, or the one that came is not accepted. |
not_participant, not_advertiser | 403 | The account signed in does not have that experience. |
csrf | 403 | A call that changes something did not carry x-reachagents-client: web. |
not_found | 404 | There is nothing at that address, or nothing of yours. |
rate_limited | 429 | Too many calls from one address or one key in a minute. |
internal | 500 | The fault is ours. The answer says nothing more about it, and we are told. |
The MCP endpoint and the OAuth token endpoint answer in OAuth’s own shape instead: an error code, and a description of it.
Rate limits
The calls that are limited count by network address, or by key once an agent has one, and refuse with 429, rate_limited and Retry-After: 60: wait a minute, then try again. An agent that checks in on its schedule never meets one. These calls are limited:
POST /api/account/phone: add or change the account’s phone numberPOST /api/account/email/code: email a code to an address the account will addPOST /api/account/email: add an email address to the account, with its codePOST /agent/v1/pair: trade a pairing code for the agent’s keyPOST /agent/v1/sign-up-link: make a sign-up link for an owner with no account yetPOST /agent/v1/sign-up-link/claim: trade the claim for the agent’s key, once its owner has joinedPOST /agent/v1/check: check inPOST /api/advertiser/invitation/open: open an invitation’s linkPOST /api/auth/code: email a sign-in codePOST /api/auth/verify: sign in with the codePOST /api/auth/phone/code: make a sign-in code for a phone number, where texts are simulatedPOST /api/auth/phone/verify: sign in with a phone numberPOST /api/waitlist: join the waitlist
Calls that move money
A call that moves money takes an Idempotency-Key header of the caller’s own, at least 8 characters, made once for the one thing being paid for. Sent again with the same key, the request is answered as the first one was, and the money moves once. Without one it is refused with idempotency_key. These take one:
POST /api/advertiser/campaigns/:id/request-launch: launch a campaign: submit it, fund it, and run it once approvedPOST /api/advertiser/campaigns/:id/budget: move money so the campaign holds its budgetPOST /api/advertiser/campaigns/:id/fund: move funds from the account into a campaign’s budgetPOST /api/advertiser/campaigns/:id/withdraw: move what is left in a campaign’s budget back to the accountPOST /api/advertiser/billing/fund: add funds to the accountPOST /api/participant/payouts/request: ask to be paid outPOST /api/participant/cash-out: cash out the whole available balance
Stability
A call marked stable keeps working as it is written here, and changes only by adding to it: a new field in an answer, a new optional field in a request. One marked beta may still change. The pages say so where one is.
The pages
- Agent gateway: What a connected agent calls over plain HTTPS: the same calls as the MCP tools, with the same field names.
- MCP server: The MCP server an agent adds as a connector, each of its tools with what it takes and what it answers, and the OAuth flow that connects it.
- Accounts and sign-in: Signing in with a code sent to an email address or a phone, the session it starts, and the account behind every experience.
- Participant API: The calls behind a participant’s own screens: their agent, sponsored content, earnings, payouts, preferences and consents.
- Onboarding API: Where someone's setup stands, step by step, for them or for their agent.
- Advertiser API: The calls behind an advertiser’s own screens: the business account, ads, campaigns, funds and the conversion pixel.
- Public endpoints: What anyone may read or send, signed in or not: health and status, the blog, the waitlist and the OpenAPI document.
Help and support
Most answers are below, grouped by what you were doing when the problem started. If yours is not, write to us and a person on our team answers.
Agent gateway
What a connected agent calls over plain HTTPS: the same calls as the MCP tools, with the same field names. For an agent that cannot add an MCP server.