# cURL

> Inspect Router requests and responses directly from a terminal.

cURL is the quickest way to validate your base URL, API key, model choice, and raw response shape before adding an SDK.

## Configure the environment

```bash
export ROUTER_BASE_URL="https://api-router.optimai.network/v1"
read -rsp "Router API key: " ROUTER_API_KEY
export ROUTER_API_KEY
echo
```

Copy the current base URL from [Developer API](/dashboard/developers). The silent prompt keeps the secret out of the command itself; use your server’s secret manager for deployed applications.

## List model editions

```bash
curl --fail-with-body --silent --show-error \
  "$ROUTER_BASE_URL/models" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  | jq
```

Choose an `id` with enough `ready_providers` for your immediate test, then respect its `context_length`, `max_output_tokens`, and `max_prompt_bytes`.

Enable paid requests for this API key in the dashboard. Generate one UUID per logical request and reuse it if the response is uncertain. `X-Max-Charge-Credits` can lower the 5-credit default maximum.

## Create a completion

```bash
ROUTER_REQUEST_ID="$(uuidgen)"
curl --fail-with-body --silent --show-error \
  "$ROUTER_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -H "Idempotency-Key: $ROUTER_REQUEST_ID" \
  -H "X-Max-Charge-Credits: 5.000000" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma3:1b",
    "messages": [
      { "role": "user", "content": "Explain edge inference in one sentence." }
    ],
    "max_tokens": 100,
    "temperature": 0.3
  }' \
  | jq -r '.choices[0].message.content'
```

## Inspect headers and errors

Add `--include` to see the status, `X-Request-Id`, and `Retry-After` headers. Keep `--fail-with-body` in scripts: it preserves the JSON error body while returning a nonzero exit status for HTTP failures.

```bash
ROUTER_BAD_REQUEST_ID="$(uuidgen)"
curl --include --silent \
  "$ROUTER_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -H "Idempotency-Key: $ROUTER_BAD_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"model":"unknown","messages":[{"role":"user","content":"Hello"}]}'
```

## Stream events

Use `--no-buffer` so cURL prints server-sent events as they arrive.

```bash
ROUTER_STREAM_ID="$(uuidgen)"
curl --no-buffer --silent --show-error \
  "$ROUTER_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -H "Idempotency-Key: $ROUTER_STREAM_ID" \
  -H "X-Max-Charge-Credits: 5.000000" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma3:1b",
    "messages": [{ "role": "user", "content": "Write a short welcome." }],
    "stream": true
  }'
```

Each payload begins with `data:`. The terminal success marker is `data: [DONE]`.

If the connection closes, look up `GET /v1/credits/requests/{request_id}` with your application key or signed-in account token to check your account's saved result and final charge. Accepted paid work can continue after disconnect; accepted provider-reported usage may still charge and is not independently verified.

Continue with the [models endpoint](https://router.optimai.network/docs/api/models.md) or [chat-completions reference](https://router.optimai.network/docs/api/chat-completions.md).