API reference

API overview

Base URL, authentication, environments, the error envelope and idempotency.

REST, JSON in and out, versioned under /v1. The interactive OpenAPI reference ships with the hosted API at /api-reference.

Base URL

https://api.routergrowth.com/v1

Authentication

Every authenticated endpoint takes a bearer key:

Authorization: Bearer rg_live_...

Two environments, chosen by the key, not by a different host:

Prefix	Environment	Behavior
`rg_test_`	sandbox	full loop (quote, reserve, settle) against mock providers; simulated data is clearly labeled
`rg_live_`	production	live provider routing; a paid call is never served simulated data

Keys are hashed at rest and shown once at creation. Mint them from the dashboard (a signed-in session; an API key cannot mint keys), list and revoke via /v1/api-keys. POST /v1/discover is the one public endpoint: it needs no key.

The endpoints

Endpoint	What it does
`POST /v1/discover`	Search capabilities and raw endpoints by job description. Free, public.
`POST /v1/inspect`	Schema, providers, price, billing conditions for one capability, or the contract of one raw endpoint. Free.
`POST /v1/run`	Execute a capability with routing and cost caps, or a raw endpoint under `max_cost`. Billable.
`GET /v1/catalog/capabilities`, `/v1/catalog/providers`, `/v1/catalog/providers/{provider}/endpoints`	The catalog as data: capabilities, providers with endpoint counts, one provider's raw endpoint list. Public.
`GET/POST /v1/spend-guard`	Daily cap and per-run ceiling; a blocked run ends as `status: blocked` and charges nothing.
`GET /v1/runs`, `GET /v1/runs/{id}`, `POST /v1/runs/{id}/cancel`	Run history and control.
`GET /v1/history?q=`, `POST /v1/history`	Everything already done to one subject (an email, domain, LinkedIn URL, handle, phone or name), derived from the run log: touches, results to reuse. Batch form for dedupe. Free.
`POST /v1/watch`, `GET /v1/watch`, `GET/DELETE /v1/watch/{id}`, `POST /v1/watch/{id}/refresh`	Save a query and refresh it: each refresh returns only the new and changed records.
`GET /v1/events`, `GET/POST /v1/webhooks`, `GET/PATCH/DELETE /v1/webhooks/{id}`, `POST /v1/webhooks/{id}/test`	Events and webhooks: replies, bounces, LinkedIn messages and dropped sessions, read as a stream or pushed to your URL, signed. Free.
`GET /v1/wallet`, `/v1/wallet/transactions`, `/v1/wallet/topups/checkout`, `/v1/wallet/auto-topup`, `/v1/wallet/invoices`, `/v1/referrals`	Wallet, ledger, top-ups, invoices, referrals.
`GET /v1/plan`, `POST /v1/plan`, `/v1/plan/cancel`, `/v1/plan/portal`	The optional monthly plan: read it with a key; choosing, changing or cancelling one needs a dashboard session (how plans work).
`GET/POST/DELETE /v1/api-keys`	Key management. Minting needs a dashboard session.
`GET /v1/email/inboxes`	The sending domains and inboxes the workspace owns, plus domains bought with `domain.register` that are not connected for email yet (`registered_domains`). Free, no provider call.
`GET/POST/DELETE /v1/{linkedin,instagram,whatsapp,gmail}/accounts`	Connected accounts: list with a key; connect and disconnect need a dashboard session.
`GET/DELETE /v1/connected-apps`	Apps connected over OAuth (MCP connectors); disconnect one instantly.
`POST /feedback`	Report a missing capability, a bug or a misleading doc from the call site, on the open Agent Feedback Protocol. Free, no key.

The dashboard's sign-in endpoints (/v1/auth/*) issue browser sessions for the dashboard; API integrations use bearer keys and never need them.

The error envelope

Every error, from any endpoint, has the same shape:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Top up your wallet to run this call.",
    "request_id": "req_1f2e..."
  }
}

Codes are stable and enumerable: see Errors. Include the request_id in a feedback report or when writing to support.

Idempotency

Send an Idempotency-Key header on POST /v1/run to make it safe to retry. A replayed key returns the original run unchanged, marked with an Idempotent-Replay: true response header, and never bills twice.

Money

All amounts are strings in USD ("0.05"), accounted internally in integer microdollars on an immutable ledger. Prices are shown before any call executes; nothing bills without a reserved quote.

Spend guard

GET /v1/spend-guard returns the organization's daily cap (a UTC day), today's spend (settled charges plus open holds) and when it resets. POST /v1/spend-guard with {"enabled": true, "daily_limit": "25"} switches it on. Once a run would push the day past the cap, it ends as status: blocked with error budget_exceeded and nothing is charged; raise or disable the cap, or wait for the reset.

Previous
WhatsApp and Gmail Next
Discover

Reading this as an agent? This page as markdown: /docs/api/overview.md · every page: /docs/llms.txt