# Quick Start

Create a key, make the first model call, inspect capabilities, and verify usage attribution.

## Before you start

All production API traffic enters through `https://seachat.ai`. The docs host is separate so developer material does not compete with the product app shell.

Use `Authorization: Bearer <token>` or `x-api-key: <token>`. API keys are for integrations. Web sessions are only for user-authenticated control plane actions such as creating a key.

If you are doing this manually, sign in to SeaChat, open API Keys, create a project key with `model:invoke` and `usage:read`, then store the returned token in `SEACHAT_API_KEY`.


## Automation path

A logged-in user session can call `POST /api/keys` to create a scoped project key. The session must include API-key write permission, and the token is returned only once.

API-key policy fields such as `spendLimitMicros` and `expiresAt` constrain key behavior, but the account quota source of truth remains the SeaChat quota account.

```bash
curl https://seachat.ai/api/keys \
  -H "Authorization: Bearer $SEACHAT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "agent integration",
    "scopes": ["model:invoke", "usage:read"],
    "spendLimitMicros": 5000000
  }'
```

## Agent runtime pattern

Agents should first read the capability catalog, then choose routes by `id`, `group`, `requiredScopes`, `inputSchema`, and `runtimeSafe`. This avoids guessing at internal paths.

Model calls should read SeaRouter help when the request shape is provider-specific. SeaRouter owns provider credentials, model aliases, managed output import, and usage attribution.

For multimodal work, query `/api/searouter/v1/help/models/search` before sending provider-shaped parameters.


## Common failures

`401 missing_credentials` means the request reached the public gateway but no API key, bearer session, or service token was accepted.

`403 route_scope_denied` means the token is valid but does not include one of the route's required scopes. Read `/api/capabilities.json` or the live capability catalog before minting a narrower replacement key.