HTTP routes
Every HTTP route the service mounts, what it needs and the status codes it returns.
All routes are on https://api.envoy.money. Tool calls need a bearer; schema discovery does not.
Support revision: envoy@2026-10. Last updated: 28 October 2026.
| Route | Auth | Use |
|---|---|---|
GET /tools | None | Every tool with its input and output schemas and annotations. No account data. |
GET /openapi.json | None | The OpenAPI document for the tool routes. |
POST /tools/{tool} | Bearer, plus proof if key-bound | Call one tool. The body is the tool's input. |
POST /mcp | Bearer, plus proof if key-bound | The same tools over MCP. See Connection and discovery. |
POST /installation/challenge | Bearer | Get a one-use challenge for a key-bound request. See request protection. |
POST /disconnect | Bearer, plus proof if key-bound | End this connection's access. |
GET /.well-known/oauth-protected-resource/mcp | None | Resource, issuer and scope for OAuth. See OAuth with PKCE. |
Call a tool
Send Content-Type: application/json and the tool's input object; get_account takes {}. The reply is always the shared envelope. The API quickstart walks through a purchase.
| Status | When |
|---|---|
200 | Success, and business outcomes that still carry a purchase. Read ok and next. |
400–503 | ok: false; the status follows error.code, as listed in Errors and reason codes. A 401 also carries WWW-Authenticate with the protected-resource metadata URL. |
404 with {"error":"NOT_FOUND"} | The tool name is not in the current catalog. Nothing ran. |
413 | The body is larger than 64 KB (INVALID_INPUT). |
429 | Over 120 calls a minute on this access token, shared with /mcp (RATE_LIMITED). Wait next.after_seconds. |
Paths are case-sensitive and have no trailing slash. The service has no versioned routes. Any path that starts with /v1/ returns 404, the same as any other path the service does not serve.
Disconnect
POST /disconnect with the current bearer ends this agent's access at Envoy and asks the authorization server to revoke the grant. A key-bound connection sends a fresh proof over this exact path and body.
200withremote_revocation: "confirmed": the grant is revoked.202withremote_revocation: "pending": Envoy has already blocked access; retry the disconnect (with a fresh proof) to confirm remote revocation.
Disconnecting does not cancel a purchase or a merchant order, and no card is released after it. Before any checkout report, call cancel_purchase first to request a stop. After a report, Envoy refuses cancellation and reconciles the purchase. If the card wasn't charged and Envoy reopens it (the purchase reads ready again), cancel_purchase works again.