Quick Start - SeaChat Developer Docs

Quick Start

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

Runnable path

Create a scoped API key

Use these steps in order. They create a narrow key, make one model call, inspect the declared capability metadata, and verify usage attribution.

Get an API key

Create a project key from the SeaChat app, or automate it with a logged-in web session token that has API-key write scope. The API key token is returned once.

export SEACHAT_SESSION_TOKEN="<web-session-token>"

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

export SEACHAT_API_KEY="sk-seaverse-..."

Call the Responses API

SeaRouter exposes an OpenAI-style Responses endpoint through SeaGate. Provider credentials stay server-side; clients send only the SeaChat key.

curl https://seachat.ai/api/searouter/llm/v1/responses \
  -H "Authorization: Bearer $SEACHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Write a concise launch checklist for an agent API."
  }'

Discover capability metadata

Agents should read the credential-aware catalog before choosing routes. It returns access, required scopes, stability, runtime safety, schemas, and examples.

curl "https://seachat.ai/api/seagate/v1/capabilities?runtime=true&includeDenied=true" \
  -H "Authorization: Bearer $SEACHAT_API_KEY"

Verify usage attribution

After the first call, query usage with the same key. Use x-request-id on retries so support, billing, and logs share one correlation id.

curl https://seachat.ai/api/searouter/v1/usage/summary \
  -H "Authorization: Bearer $SEACHAT_API_KEY"

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.

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.