# SeaMeet Sync Pro API -- LLM Guide

This file is the implementation brief for coding agents integrating the SeaMeet
Sync Pro API.

## API vs MCP

Use the local SeaMeet MCP server when the user wants an agent to operate the
desktop app, local recordings, screenshots, live transcripts, summaries, action
items, templates, or artifact bundles.

Use the Sync Pro API when building a cloud integration over synced recordings,
transcript sections, signed media URLs, usage, API keys, and webhooks.

Use Media/STT Worker docs only for advanced first-party session flows until
those routes support normal SeaMeet API keys.

MCP install:

```bash
claude mcp add seameet -- npx -y @seameet/mcp
codex mcp add seameet -- npx -y @seameet/mcp
```

MCP references:

- MCP install guide: https://app.seameet.ai/mcp/
- MCP LLM reference: https://app.seameet.ai/mcp/llms.txt
- MCP tools JSON: https://app.seameet.ai/mcp/tools.json
- Agent skills catalog: https://app.seameet.ai/.well-known/skills/index.json

## Base URLs

- Production Sync API: https://api.seameet.ai/functions/v1/sync-api
- Production Media/STT Worker: https://seameet-stt-proxy.seameet.workers.dev
- Development Sync API: https://ifcxzlaynrdykqmcwgbh.supabase.co/functions/v1/sync-api
- Development Media/STT Worker: https://seameet-stt-proxy-dev.seameet.workers.dev

Use production URLs for user-facing integrations unless the user explicitly
asks for dev.

Media/STT Worker endpoints are advanced first-party session only unless noted
otherwise. They are not part of the public X-Api-Key Sync API surface.

## Critical Routing Rule

Do not call `/sync-api#delta`, `/sync-api#get-sections`, or any
`/sync-api#...` path.

Those are OpenAPI documentation anchors only. The wire URL is always the Sync
API base URL. Put the operation name in the JSON body as `op`.

Correct:

```bash
curl -sS "https://api.seameet.ai/functions/v1/sync-api" \
  -H "X-Api-Key: $SEAMEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"delta","since":null}'
```

Node fetch:

```js
const baseUrl = 'https://api.seameet.ai/functions/v1/sync-api';
const apiKey = process.env.SEAMEET_API_KEY;

async function callSeaMeet(body) {
  const response = await fetch(baseUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': apiKey,
    },
    body: JSON.stringify(body),
  });

  const json = await response.json();
  if (!response.ok) {
    throw new Error(`SeaMeet API ${response.status}: ${JSON.stringify(json)}`);
  }
  return json;
}

const firstSync = await callSeaMeet({ op: 'delta', since: null });
console.log(firstSync.assets);
```

Expected first successful response shape:

```json
{
  "assets": [],
  "versions": [],
  "hasMore": false
}
```

Wrong:

```bash
curl https://api.seameet.ai/functions/v1/sync-api#delta
```

## Authentication

For normal public API clients:

- `X-Api-Key: smk_<40 hex>`

Personal API keys are created at https://app.seameet.ai/account. Read-only keys
can list/read assets and usage. Write-scoped keys are required for mutations
such as webhooks, uploads, sharing, trash, and restore. API key management ops
require a user JWT.

First-party app sessions may also authenticate with
`Authorization: Bearer <supabase-user-access-token>`.

## Common Flows

### List recordings

Call `delta`:

```json
{"op":"delta","since":null}
```

Store the returned cursor and pass it as `since` next time.

### Read transcript, summary, chapters, action items, or notes

Call `get-sections`:

```json
{"op":"get-sections","assetId":"<asset uuid>"}
```

The response contains per-section text rows. Content may be reveal-cap masked
server-side for callers without Sync Pro or without full access.

### Get a signed media download URL

Call `download-url`:

```json
{"op":"download-url","assetId":"<asset uuid>","disposition":"inline"}
```

Use `download-urls` for batches up to 50 asset IDs.

### Register an outbound webhook

Call `webhook-create` with a public HTTPS URL:

```json
{
  "op": "webhook-create",
  "url": "https://example.com/seameet/webhook",
  "events": ["recording.synced", "ai.ready"]
}
```

SeaMeet rejects internal, loopback, and link-local webhook hosts.

### Verify webhook signatures

Every delivery includes:

- `X-SeaMeet-Event`
- `X-SeaMeet-Delivery`
- `X-SeaMeet-Signature`

Signature format:

```text
t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "{t}.{rawBody}")>
```

Use the raw request body, reject stale timestamps, and return any 2xx response
to acknowledge delivery.

### Use Media/STT Worker endpoints

The Worker base URL is separate from the Sync API base URL.
Worker file, Gemini-push, and realtime STT streaming endpoints currently
require first-party app session bearer auth, not a personal API key.
`/v1/health` is unauthenticated.

- `POST /v1/file`
- `POST /v1/gemini-push`
- `GET /v1/health`
- `wss://.../v1/stream`

For production, call:

```text
https://seameet-stt-proxy.seameet.workers.dev/v1/file
```

## Common Errors

- `401`: missing or invalid `X-Api-Key` for public API-key calls, or invalid bearer token for first-party app sessions.
- `403`: not entitled, unverified account, or insufficient API-key scope.
- `404`: asset/share/webhook/key not visible to this caller.
- `409`: conflict, duplicate client reference, or media not fully synced.
- `413`: quota exceeded or media too large.
- `504`: Worker push timed out; use documented fallback behavior.

## Machine-Readable References

- Human reference: https://app.seameet.ai/api/
- OpenAPI YAML: https://app.seameet.ai/api/openapi.yaml
- Sync-only OpenAPI YAML: https://app.seameet.ai/api/sync-openapi.yaml
- Worker-only OpenAPI YAML: https://app.seameet.ai/api/media-stt-openapi.yaml
- Realtime STT WebSocket protocol: https://app.seameet.ai/api/stream-protocol.md
- Task recipes: https://app.seameet.ai/api/tasks.json
- App LLM index: https://app.seameet.ai/llms.txt
- MCP LLM reference: https://app.seameet.ai/mcp/llms.txt
- MCP tools JSON: https://app.seameet.ai/mcp/tools.json
- Agent skills catalog: https://app.seameet.ai/.well-known/skills/index.json