Skip to Content
Docs

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

WhoHow
A connected agentIts 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 personThe 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.
AnyoneThe 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 as If-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:

CodeStatusWhat it means
invalid_input400The request is not of the shape the call takes. details names each field that is wrong, and why.
unauthorized401No session or key came with it, or the one that came is not accepted.
not_participant, not_advertiser403The account signed in does not have that experience.
csrf403A call that changes something did not carry x-reachagents-client: web.
not_found404There is nothing at that address, or nothing of yours.
rate_limited429Too many calls from one address or one key in a minute.
internal500The 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 number
  • POST /api/account/email/code: email a code to an address the account will add
  • POST /api/account/email: add an email address to the account, with its code
  • POST /agent/v1/pair: trade a pairing code for the agent’s key
  • POST /agent/v1/sign-up-link: make a sign-up link for an owner with no account yet
  • POST /agent/v1/sign-up-link/claim: trade the claim for the agent’s key, once its owner has joined
  • POST /agent/v1/check: check in
  • POST /api/advertiser/invitation/open: open an invitation’s link
  • POST /api/auth/code: email a sign-in code
  • POST /api/auth/verify: sign in with the code
  • POST /api/auth/phone/code: make a sign-in code for a phone number, where texts are simulated
  • POST /api/auth/phone/verify: sign in with a phone number
  • POST /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 approved
  • POST /api/advertiser/campaigns/:id/budget: move money so the campaign holds its budget
  • POST /api/advertiser/campaigns/:id/fund: move funds from the account into a campaign’s budget
  • POST /api/advertiser/campaigns/:id/withdraw: move what is left in a campaign’s budget back to the account
  • POST /api/advertiser/billing/fund: add funds to the account
  • POST /api/participant/payouts/request: ask to be paid out
  • POST /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.