# Quick Start

Install the SDK, construct a client with one Bearer key, and make your first /v1 chat call (SDK and curl).

## Before you start

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

The Platform API uses a **single credential**: a bearer API key sent as `Authorization: Bearer <apiKey>`. The gateway rejects requests that carry more than one credential type, so never send both `Authorization` and `x-api-key`. The SDK always sends exactly the one Bearer header.

Tenancy is **user-scoped**: each key acts as a single user. There is no separate organization or project credential.


## Get an API key

API keys are minted at `POST /v1/auth/keys` after an email / web login at `https://seachat.ai`. Create your first key from the account / API-keys area of the SeaChat web app and copy the token immediately; the full secret is shown only once.

Once you already have a key, you can mint more programmatically (useful for CI runners or per-service credentials) with `client.authKeys.create`.

```bash
export SEACHAT_API_KEY="sk-..."

# Mint an additional key from an existing one:
curl https://seachat.ai/v1/auth/keys \
  -H "Authorization: Bearer $SEACHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"ci-runner"}'
```

## First call with the SDK

Install `@seachat/platform-sdk`, construct one client, and reuse it across your app. `client.me.get()` verifies the key; `client.chat.completions.create` runs an OpenAI-compatible completion.

```bash
import { SeaChat } from "@seachat/platform-sdk";

const client = new SeaChat({ apiKey: process.env.SEACHAT_API_KEY! });

const me = await client.me.get();
console.log("Authenticated as:", me.subject);

const completion = await client.chat.completions.create({
  model: "claude-opus-4-8",
  messages: [{ role: "user", content: "Write a one-line launch checklist." }],
  max_tokens: 128,
});
console.log(completion.choices[0].message.content);
```

## First call with curl

The same request without the SDK. Use the one Bearer header and post to `/v1/chat/completions`.

```bash
curl https://seachat.ai/v1/chat/completions \
  -H "Authorization: Bearer $SEACHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-4-8","messages":[{"role":"user","content":"Write a one-line launch checklist."}]}'
```

## Common failures

`401` means the request reached the gateway but no valid credential was accepted. Re-check `Authorization: Bearer <apiKey>` and confirm the key is not revoked.

`403` means the key is valid but lacks one of the route's required scopes (for example `model:invoke` for inference or `usage:read` for usage). Mint a key with the scopes you need, or read the capability catalog at `/v1/capabilities`.

Any non-2xx response throws a `SeaChatError` in the SDK, carrying `status`, `code`, `message`, and `requestId`. Branch on `err instanceof SeaChatError`, then include `requestId` when contacting support.