# Quickstart: API

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: [hello@jell.run](mailto:hello@jell.run?subject=Early%20access).

## 1. Create an account

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

```bash
curl -X POST https://api.jell.run/v1/dev/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "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](/dashboard) and mint a live key there.

```bash
export JELL_API_KEY=rg_test_...
```

## 2. Find a capability

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

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

```bash
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:

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

```bash
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/history?q=alex.rivera@example.com" -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](/docs/api/runs#history-for-a-subject)).

Every key gets a web view of the same state, balance, keys, runs and usage, on the [dashboard](/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.

```bash
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.

## Next

- [Raw endpoints](/docs/api/endpoints): addressing, the hold and settle rules, health.
- [Run reference](/docs/api/run): routing options, waterfall, response fields.
- [Errors](/docs/api/errors): stable codes and retry guidance.
- [How it works](/docs/how-it-works): the billing model behind the calls.