# 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.routergrowth.com` opens to early-access keys as provider terms are signed. Request a key: [hello@routergrowth.com](mailto:hello@routergrowth.com?subject=Early%20access).

## 1. Create an account

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

```bash
curl -X POST https://api.routergrowth.com/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: sign in through the [dashboard](/dashboard) with an emailed code and mint a live key there.

```bash
export ROUTERGROWTH_API_KEY=rg_test_...
```

## 2. Find a capability

```bash
curl -X POST https://api.routergrowth.com/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.routergrowth.com/v1/inspect \
  -H "Authorization: Bearer $ROUTERGROWTH_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.routergrowth.com/v1/run \
  -H "Authorization: Bearer $ROUTERGROWTH_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.routergrowth.com/v1/wallet -H "Authorization: Bearer $ROUTERGROWTH_API_KEY"
curl https://api.routergrowth.com/v1/runs   -H "Authorization: Bearer $ROUTERGROWTH_API_KEY"
```

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.

## Next

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