Get started

Quickstart: API

A first REST call in five minutes: signup, inspect, run, wallet.

A first billable-shaped call in five minutes, against the sandbox. The interface is final; the same requests work against production with an rg_live_ key.

Early access. The sandbox runs the full loop in labeled mock mode; the hosted API at api.jell.run opens to early-access keys as provider terms are signed. Request a key: [email protected].

1. Create an account

Sandbox signup mints an organization, a test key and $1 of promotional credit:

curl -X POST https://api.jell.run/v1/dev/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "organization_name": "Acme"}'
# → {"api_key": "rg_test_...", ...}  (shown only once, store it now)

On production this route is closed: create an account or sign in on the dashboard and mint a live key there.

export JELL_API_KEY=rg_test_...

2. Find a capability

curl -X POST https://api.jell.run/v1/discover \
  -d '{"query": "find a verified email for a person"}'

Discover is free and public: it searches the catalog, never executes a paid call, and returns candidates with status, providers and starting_price.

3. Inspect it

curl -X POST https://api.jell.run/v1/inspect \
  -H "Authorization: Bearer $JELL_API_KEY" \
  -d '{"capability": "contact.find"}'

The response is the contract: input_schema, output_fields, per-provider offers with exact prices, and billing conditions. Always show a user the price before a billable run.

4. Run it

curl -X POST https://api.jell.run/v1/run \
  -H "Authorization: Bearer $JELL_API_KEY" \
  -H "Idempotency-Key: my-unique-value-1" \
  -d '{
    "capability": "contact.find",
    "input": {"first_name": "Alex", "last_name": "Rivera", "company_domain": "example.com"},
    "routing": {"provider": "auto", "strategy": "best_value", "max_cost": "0.10"}
  }'

A successful response looks like:

{
  "run_id": "run_...",
  "status": "succeeded",
  "capability": "contact.find",
  "provider": "...",
  "routing_reason": "auto: best_value picked ...",
  "billing": {"currency": "USD", "quoted": "0.05", "charged": "0.05", "platform_funded": true},
  "timing": {"duration_ms": 842},
  "attempts": [{"provider": "...", "outcome": "succeeded", "duration_ms": 842, "detail": null}],
  "result": {"...": "..."},
  "request_id": "req_...",
  "created_at": "2026-09-02T09:30:00+00:00"
}

The Idempotency-Key header makes the call safe to retry: a replay returns the original run with an Idempotent-Replay: true response header instead of executing again.

5. Check the wallet and history

curl https://api.jell.run/v1/wallet -H "Authorization: Bearer $JELL_API_KEY"
curl https://api.jell.run/v1/runs   -H "Authorization: Bearer $JELL_API_KEY"
curl "https://api.jell.run/v1/[email protected]" -H "Authorization: Bearer $JELL_API_KEY"

The last one is the run log read by subject: every run that mentions that person in its input or result, the outbound touches, and paid results you can reuse instead of buying again. Check it before enriching or messaging anyone (details).

Every key gets a web view of the same state, balance, keys, runs and usage, on the dashboard. Agents read it over the API; you read it in the browser.

6. Go one tier down when you need to

Discover also returns raw endpoints: one provider's own endpoint, with kind: "endpoint". Inspect one to get the provider's request shape, then run it with max_cost set, because a raw run has no quote and settles on the provider's measured cost after the call.

curl -X POST https://api.jell.run/v1/discover \
  -d '{"query": "tiktok video comments", "kind": "endpoint"}'

curl -X POST https://api.jell.run/v1/inspect \
  -H "Authorization: Bearer $JELL_API_KEY" \
  -d '{"provider": "dataforseo", "endpoint": "/v3/serp/google/organic/live/advanced"}'

curl -X POST https://api.jell.run/v1/run \
  -H "Authorization: Bearer $JELL_API_KEY" \
  -d '{
    "provider": "dataforseo",
    "endpoint": "/v3/serp/google/organic/live/advanced",
    "input": {"keyword": "best crm", "location_code": 2840, "language_code": "en"},
    "routing": {"max_cost": "0.05"}
  }'

result.data is the provider's payload untouched. When discover says a capability wraps the endpoint, prefer the capability: normalized output, a quote, failover.

Raw endpoints: addressing, the hold and settle rules, health.
Run reference: routing options, waterfall, response fields.
Errors: stable codes and retry guidance.
How it works: the billing model behind the calls.

Previous
How it works Next
Quickstart: CLI

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