{
  "name": "SeaMeet Sync Pro API task recipes",
  "version": "0.1.0",
  "baseUrls": {
    "production": {
      "syncApi": "https://api.seameet.ai/functions/v1/sync-api",
      "mediaStt": "https://seameet-stt-proxy.seameet.workers.dev"
    },
    "development": {
      "syncApi": "https://ifcxzlaynrdykqmcwgbh.supabase.co/functions/v1/sync-api",
      "mediaStt": "https://seameet-stt-proxy-dev.seameet.workers.dev"
    }
  },
  "routingRules": [
    "Do not call /sync-api#delta or any /sync-api#... path.",
    "OpenAPI /sync-api#... entries are documentation anchors only.",
    "Always POST to the Sync API base URL with an op value in the JSON body.",
    "Normal public API clients authenticate to the Sync API with only X-Api-Key.",
    "Worker endpoints are separate from Sync API and currently require first-party session bearer auth, except /v1/health.",
    "Realtime STT is a WebSocket at wss://<media-stt-host>/v1/stream and is documented in /api/stream-protocol.md, not OpenAPI."
  ],
  "headers": {
    "personalApiKey": {
      "X-Api-Key": "smk_<40 hex>",
      "Content-Type": "application/json"
    },
    "firstPartySession": {
      "Authorization": "Bearer <supabase-user-access-token>",
      "Content-Type": "application/json"
    }
  },
  "recipes": [
    {
      "id": "list-recordings",
      "title": "List recent recordings and shared assets",
      "endpoint": "syncApi",
      "method": "POST",
      "body": {
        "op": "delta",
        "since": null
      },
      "notes": [
        "Use the returned cursor as since on the next call.",
        "Returns owned and shared assets plus changed text sections."
      ]
    },
    {
      "id": "read-recording-text",
      "title": "Read transcript, summary, chapters, action items, or notes",
      "endpoint": "syncApi",
      "method": "POST",
      "body": {
        "op": "get-sections",
        "assetId": "<asset uuid>"
      },
      "notes": [
        "This is the sanctioned text-read path.",
        "Reveal caps are applied server-side for limited callers."
      ]
    },
    {
      "id": "get-one-media-url",
      "title": "Get a short-lived media download URL",
      "endpoint": "syncApi",
      "method": "POST",
      "body": {
        "op": "download-url",
        "assetId": "<asset uuid>",
        "disposition": "inline"
      },
      "notes": [
        "Use disposition inline for streaming and thumbnails.",
        "Use disposition attachment for user downloads."
      ]
    },
    {
      "id": "get-many-media-urls",
      "title": "Get up to 50 short-lived media URLs",
      "endpoint": "syncApi",
      "method": "POST",
      "body": {
        "op": "download-urls",
        "assetIds": ["<asset uuid>"],
        "disposition": "inline"
      },
      "notes": [
        "Use this for thumbnail grids or batch export views."
      ]
    },
    {
      "id": "create-webhook",
      "title": "Subscribe to outbound webhooks",
      "endpoint": "syncApi",
      "method": "POST",
      "body": {
        "op": "webhook-create",
        "url": "https://example.com/seameet/webhook",
        "events": ["recording.synced", "ai.ready"]
      },
      "notes": [
        "Requires a verified account, Sync Pro, and JWT or write-scoped API key.",
        "URL must be public HTTPS; internal and loopback hosts are rejected.",
        "The returned secret is needed to verify deliveries."
      ]
    },
    {
      "id": "verify-webhook",
      "title": "Verify a webhook delivery",
      "endpoint": "yourWebhookReceiver",
      "method": "POST",
      "signature": {
        "header": "X-SeaMeet-Signature",
        "format": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"{t}.{rawBody}\")>",
        "recommendedToleranceSeconds": 300
      },
      "notes": [
        "Use the raw body bytes, not parsed and re-serialized JSON.",
        "Return any 2xx status to acknowledge delivery."
      ]
    },
    {
      "id": "transcribe-synced-file",
      "title": "Run managed transcription for a synced asset",
      "endpoint": "mediaStt",
      "path": "/v1/file",
      "method": "POST",
      "auth": "firstPartySession",
      "body": {
        "assetId": "<asset uuid>",
        "language": "en"
      },
      "notes": [
        "Call the Worker base URL, not the Sync API base URL.",
        "A 409 not_synced response means the asset is not complete in R2 yet."
      ]
    },
    {
      "id": "realtime-stt-stream",
      "title": "Stream live audio for realtime STT",
      "endpoint": "mediaStt",
      "path": "/v1/stream",
      "scheme": "wss",
      "auth": "firstPartySession",
      "protocol": "https://app.seameet.ai/api/stream-protocol.md",
      "notes": [
        "This is a WebSocket protocol, not an OpenAPI REST endpoint.",
        "Send PCM16 mono 16 kHz binary frames and optional finalize JSON.",
        "Requires a first-party Supabase user access token today."
      ]
    },
    {
      "id": "check-worker-health",
      "title": "Check live STT session counts",
      "endpoint": "mediaStt",
      "path": "/v1/health",
      "method": "GET",
      "auth": "none",
      "notes": [
        "Unauthenticated health endpoint; counts only."
      ]
    }
  ],
  "references": {
    "human": "https://app.seameet.ai/api/",
    "llms": "https://app.seameet.ai/api/llms.txt",
    "openapi": "https://app.seameet.ai/api/openapi.yaml",
    "syncOpenapi": "https://app.seameet.ai/api/sync-openapi.yaml",
    "mediaSttOpenapi": "https://app.seameet.ai/api/media-stt-openapi.yaml",
    "streamProtocol": "https://app.seameet.ai/api/stream-protocol.md"
  }
}