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.jell.run/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.
`GET /v1/wallet`, `/v1/wallet/transactions`, `/v1/wallet/topups/checkout`, `/v1/wallet/auto-topup`, `/v1/referrals`	Wallet, ledger, top-ups, referrals.
`GET/POST/DELETE /v1/api-keys`	Key management. Minting needs a dashboard session.
`GET/DELETE /v1/connected-apps`	Apps connected over OAuth (MCP connectors); disconnect one instantly.

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