> For the complete documentation index, see [llms.txt](https://docs.robotmoney.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.robotmoney.com/api-reference/overview.md). # Overview RobotMoney exposes a **REST + JSON-RPC HTTP surface** and an **MCP server surface**. The same primitives are used by humans and agents. Only authentication differs. ### Base URLs | Environment | URL | | -------------- | --------------------------------------- | | **Production** | `https://api.robotmoney.com/v1` | | **Sandbox** | `https://staging-api.robotmoney.com/v1` | ### Authentication | Caller | Mechanism | | ------------------- | --------------------------------------------------------------- | | **Human owners** | Self-serve email and password, or a linked wallet | | **Tenant agents** | One-time `brain_ak_...` key exchanged for a five-minute JWT | | **Tenant API keys** | `brain_sk_...` read keys where API-key auth is enabled | | **MCP agents** | SIWX over Base plus on-chain scope hash | | **Service callers** | Scoped service credential for approved backend and ops use only | [**Authentication reference**](/api-reference/authentication.md) ### Representative Endpoints ``` POST /v1/raw/ingest // ingest a Raw artifact GET /v1/ledger/transactions // query structured Ledger records POST /v1/wiki/question // NL query over memory POST /v1/agents // create a tenant agent and one-time agent key POST /token // exchange the agent key for a five-minute JWT POST /v1/authorizations // decision-only payment authorization POST /v1/authorizations/{id}/approve // owner approves a needs-review decision POST /v1/authorizations/{id}/void // owner releases an unpaid approval GET /v1/usage/authorizations // recorded-decision usage meter PUT /v1/policy/headless-limits // set auto-approval limits for external decisions POST /v1/policy/{tenant_id}/compose // compose a candidate policy POST /v1/policy/{tenant_id}/sign // sign + activate POST /v1/execution/agents/register // register an external agent POST /v1/agents/run // route -> resolve -> propose (gated) POST /v1/payment-intents // propose a payment POST /v1/payment-intents/{id}/approve // approver signs POST /v1/payment-intents/{id}/execute // run §6 gate; returns 202 GET /v1/audit/event/{event_id} // event + Merkle inclusion proof GET /v1/proof/{action_id} // canonical Proof for an action DELETE /v1/tenants/{id} // GDPR right-to-erasure (self-tenant only) ``` ### Endpoint Reference | Section | What's Covered | | ------------------------- | ------------------------------------------------------------------------- | | Authentication | Owner sessions, tenant agent key exchange, API keys, SIWX, scopes | | Authorizations | Decision-only `approved`, `needs_review`, or `blocked` responses | | Headless Limits | Server-managed decision envelopes for `execution: external` | | Usage | Recorded authorization counts for billing and allowance views | | Sources and Raw Ingestion | Ingest artifacts directly, provider webhooks, inspect and tombstone | | Ledger | Query transactions, balances, counterparties, invoices, reconcile | | Wiki | NL questions, entity browsing, evidence chains, memory pages | | Policy | Compose, sign, evaluate, lint, simulate, diff (tenant-scoped) | | Agents | Register, list catalog, route, run, halt, runs / why / gate-trace / proof | | Actions (Payment Intents) | Propose, approve / reject, execute (runs §6 gate), pause / resume | | Audit | Events, entity history, Merkle proofs, verify, export, Proof artifact | | MCP Surface | JSON-RPC tools, resources, prompts, on-chain scope check | ### Provenance on Every Response Every response from Wiki, Policy, and Agent endpoints carries provenance. | Field | Description | | -------------------- | ---------------------------------------------------------------------------- | | `source_ids` | Raw artifact ids that produced a Ledger row | | `evidence_ids` | Raw-parsed row ids the extractor consulted | | `evidence_path` | Returned by Wiki answers: the chain of Raw / Ledger refs the answer rests on | | `provenance` | `extracted`, `inferred`, `ambiguous`, `human_confirmed`, `agent_contributed` | | `confidence` | Calibrated 0–1 score on every derived row | | `policy_decision_id` | Policy decision row joined to a PaymentIntent or authorization decision | ### Versioning The API is versioned in the URL path: `/v1/...`. Breaking changes always bump the version. Non-breaking additions (new endpoints, new fields) ship in place. | Behaviour | Considered Breaking? | | ------------------------------------- | -------------------- | | Adding an endpoint | No | | Adding a field to a response | No | | Adding an optional field to a request | No | | Removing or renaming a field | Yes | | Changing default behaviour | Yes | | Changing an HTTP status code | Yes | ### Rate Limits Rate limits apply per API key. | Tier | Requests / min | Burst | Concurrent WebSockets | | -------------- | -------------- | ------ | --------------------- | | **Free** | 60 | 100 | 5 | | **Developer** | 600 | 1,000 | 25 | | **Production** | 6,000 | 10,000 | 250 | | **Enterprise** | Custom | Custom | Custom | When rate-limited: ```http HTTP/1.1 429 Too Many Requests Retry-After: 12 X-RateLimit-Limit: 600 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1700000000 ``` {% hint style="warning" %} Always honour the `Retry-After` header. Aggressive retries against rate limits will result in temporary key suspension. {% endhint %} ### Errors All errors share a common shape. ```json { "error": { "code": "policy_denied", "message": "Counterparty not approved", "details": { "counterparty_id": "cp_x", "policy_version": 3 }, "request_id": "req_8f3a92...", "docs_url": "https://docs.robotmoney.com/resources/errors#policy_denied" } } ``` | Status | Meaning | | ------ | ------------------------------------------- | | `400` | Validation error | | `401` | Authentication failed | | `403` | Authenticated, but lacks scope | | `404` | Not found | | `409` | Conflict (e.g. duplicate registration) | | `422` | Policy denied or escalation required | | `429` | Rate limit exceeded | | `500` | Internal error (always logs a `request_id`) | ### What's Next
AuthenticationEmail, wallet, and SIWX in detail.Authentication
MCP SurfaceSame primitives, MCP shape.Overview