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

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/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000000

Always honour the Retry-After header. Aggressive retries against rate limits will result in temporary key suspension.

Errors

All errors share a common shape.

{
  "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

Authentication

Email, wallet, and SIWX in detail.

Authentication

MCP Surface

Same primitives, MCP shape.

Overview