{
  "openapi": "3.1.0",
  "info": {
    "title": "dropspace API",
    "version": "1.74.1",
    "description": "create launches with AI-generated content, generate images and videos, manage writing personas, and publish to Twitter, Reddit, LinkedIn, Facebook, Instagram, TikTok, and more.",
    "contact": {
      "name": "dropspace",
      "url": "https://www.dropspace.dev"
    },
    "x-guidance": "dropspace lets agents schedule multi-platform social media launches. most endpoints require an API key (Authorization: Bearer ds_live_...) - create one at https://www.dropspace.dev/settings/api. POST /launches and related read endpoints additionally accept x402 wallet auth: x402 wallets get 5 free launches per month per identity, then $0.55 USDC on Base per launch. publishing is always free; only launch creation past the free tier settles. reddit launches can fan out to multiple communities via platform_contents.reddit.metadata.subreddits (string[], max 10, one post each) with an optional metadata.first_comment - each subreddit has its own promotional rules, so target a few genuinely relevant ones rather than blasting. see https://www.dropspace.dev/docs#x402-payments for the full payment flow and https://api.dropspace.dev/llms.txt for product context."
  },
  "x-discovery": {
    "ownershipProofs": [
      "domain:api.dropspace.dev",
      "wellknown:https://api.dropspace.dev/.well-known/x402"
    ]
  },
  "x-service-info": {
    "categories": [
      "social",
      "marketing",
      "automation"
    ],
    "docs": {
      "homepage": "https://www.dropspace.dev",
      "apiReference": "https://www.dropspace.dev/docs",
      "llms": "https://api.dropspace.dev/llms.txt"
    }
  },
  "servers": [
    {
      "url": "https://api.dropspace.dev",
      "description": "production"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "launches",
      "description": "create, manage, and publish launches across multiple platforms."
    },
    {
      "name": "audience",
      "description": "follower counts and growth-over-time for the connected account's instagram, youtube, tiktok, twitter, and facebook. read from the official platform apis. requires an api key whose account has the platform connected."
    },
    {
      "name": "trial reels",
      "description": "trial reel programs: dropspace reshares your strongest Instagram reels as trial reels (shown to non-followers first) at your best hours, then checks each at 1, 3, and 7 days. pro and premium."
    },
    {
      "name": "songs",
      "description": "songs for song to reels (pro and premium): add a song from a YouTube or SoundCloud link or a public audio file url (the web app uploads a file), read it back with its waveform once the import is done, get its lyrics with word timings, and make 9:16 lyric reels from a snippet (5 to 30 seconds): the snippet's audio under clips from the media library or a gradient, with the lyrics burned in; a finished reel lands in the media library and can become a draft launch. the audio is fetched and converted on the server (AAC in m4a, cut at 15 minutes), so a new song is `pending` until it is `ready` or `failed`; a reel renders the same way. at most 100 songs per user; reels count against the plan's song reels per billing period (pro 30, premium 100)."
    },
    {
      "name": "reports",
      "description": "saved reports: markdown an AI app saves through the MCP workflows (Instagram audit, best-times plan, winners report) or your own client saves through the API. the reports page in the app lists them. every plan."
    },
    {
      "name": "reddit",
      "description": "reddit-specific discovery. find where your ICP lives and where THIS account has standing to post, before you fan a launch out. requires an api key whose account has reddit connected."
    },
    {
      "name": "media library",
      "description": "the user's own photos and videos. autopilot posts them when its media_source is library or mixed, choosing each item by its description."
    },
    {
      "name": "personas",
      "description": "manage AI writing personas for content generation."
    },
    {
      "name": "autopilot",
      "description": "the autonomous content engine. autopilot studies your post performance nightly, drafts new posts in your voice, and schedules them on your connected accounts. review-first by default; pro and premium plans only."
    },
    {
      "name": "recommendations",
      "description": "actionable insights computed from your organic post performance. dropspace sweeps your recent posts' metrics every 30 minutes, detects winners and underperformers against your own baseline, and turns them into one-click actions: repost, cross-post, boost, promote into autopilot, or pause what isn't working."
    },
    {
      "name": "media",
      "description": "generate AI images and videos for your launches."
    },
    {
      "name": "account",
      "description": "your profile, and the billing portal hand-off."
    },
    {
      "name": "connections",
      "description": "view and disconnect your OAuth platform connections."
    },
    {
      "name": "dropspace",
      "description": "check which official dropspace accounts are connected and available for posting."
    },
    {
      "name": "API keys",
      "description": "manage your API keys for authentication."
    },
    {
      "name": "webhooks",
      "description": "manage webhook endpoints for event notifications."
    },
    {
      "name": "usage",
      "description": "check your current plan, billing period, and usage limits."
    },
    {
      "name": "recap",
      "description": "what you published in the last 30 days from your own connected accounts: the numbers behind the recap page."
    },
    {
      "name": "affiliate",
      "description": "your affiliate status, link, sign-ups, and commission totals, with the program terms."
    },
    {
      "name": "credits",
      "description": "purchase and manage credit packs for MPP (Stripe) agents. credits let agents prepay for launches in bulk, reducing per-transaction fees."
    },
    {
      "name": "boosts",
      "description": "create paid boost campaigns on meta for organic facebook or instagram launches. boosts always start PAUSED. activate them explicitly to begin ad spend. ad budget is billed by meta to the user's connected ad account, not by dropspace."
    },
    {
      "name": "changelog",
      "description": "machine-readable release history - public, no API key required."
    }
  ],
  "paths": {
    "/launches": {
      "get": {
        "tags": [
          "launches"
        ],
        "summary": "list launches with pagination",
        "operationId": "listLaunches",
        "security": [
          {
            "apiKey": []
          },
          {
            "agentPaymentAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LaunchListItem"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "payment required: agent payment auth (x402 or MPP). launch creation beyond the free tier (5/month) costs $0.55 via x402 (crypto) or $0.60 via MPP (card). Authoritative x402 wallet challenge ships in the PAYMENT-REQUIRED header per x402 v2 spec; the body x402 block is a convenience for integrators inspecting JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "PAYMENT_001"
                        },
                        "message": {
                          "type": "string",
                          "example": "payment required: $0.55 USDC per launch (x402, 5 free/month) or $0.60 per launch (MPP)"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    },
                    "x402": {
                      "type": "object",
                      "description": "x402 protocol metadata (mirrors PAYMENT-REQUIRED header content)",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 2
                        },
                        "scheme": {
                          "type": "string",
                          "example": "exact"
                        },
                        "network": {
                          "type": "string",
                          "example": "base-mainnet"
                        },
                        "asset": {
                          "type": "string",
                          "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "description": "USDC contract address on Base"
                        },
                        "asset_name": {
                          "type": "string",
                          "example": "USDC"
                        },
                        "amount_atomic": {
                          "type": "string",
                          "example": "550000",
                          "description": "USDC amount in atomic units (6 decimals)"
                        },
                        "price_usd": {
                          "type": "string",
                          "example": "0.55"
                        },
                        "pay_to": {
                          "type": "string",
                          "description": "receiver wallet address"
                        },
                        "resource": {
                          "type": "string",
                          "example": "POST /launches"
                        },
                        "resource_url": {
                          "type": "string",
                          "example": "https://api.dropspace.dev/launches",
                          "description": "canonical URL wallets sign EIP-712 against"
                        },
                        "max_timeout_seconds": {
                          "type": "integer",
                          "example": 300
                        }
                      }
                    },
                    "mpp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 1
                        },
                        "method": {
                          "type": "string",
                          "example": "stripe"
                        },
                        "intent": {
                          "type": "string",
                          "example": "charge"
                        },
                        "currency": {
                          "type": "string",
                          "example": "usd"
                        },
                        "amount_cents": {
                          "type": "integer",
                          "example": 60
                        },
                        "resource": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "items per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "filter by launch status (draft, manual, trigger, scheduled, paused, running, completed, partial, failed, cancelled)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      },
      "post": {
        "tags": [
          "launches"
        ],
        "summary": "create a launch with AI-generated or custom content",
        "operationId": "createLaunch",
        "security": [
          {
            "apiKey": []
          },
          {
            "agentPaymentAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Launch"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: validation error; UPLOAD_001: unsupported media type; UPLOAD_002: media file too large; UPLOAD_003: media storage upload failed; LAUNCH_007: platform requirements not met (e.g. Instagram/TikTok need media); CONTENT_004: content blocked by official-account safety moderation (genuine rejection: do not resubmit the same content)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "payment required: agent payment auth (x402 or MPP). launch creation beyond the free tier (5/month) costs $0.55 via x402 (crypto) or $0.60 via MPP (card). Authoritative x402 wallet challenge ships in the PAYMENT-REQUIRED header per x402 v2 spec; the body x402 block is a convenience for integrators inspecting JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "PAYMENT_001"
                        },
                        "message": {
                          "type": "string",
                          "example": "payment required: $0.55 USDC per launch (x402, 5 free/month) or $0.60 per launch (MPP)"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    },
                    "x402": {
                      "type": "object",
                      "description": "x402 protocol metadata (mirrors PAYMENT-REQUIRED header content)",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 2
                        },
                        "scheme": {
                          "type": "string",
                          "example": "exact"
                        },
                        "network": {
                          "type": "string",
                          "example": "base-mainnet"
                        },
                        "asset": {
                          "type": "string",
                          "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "description": "USDC contract address on Base"
                        },
                        "asset_name": {
                          "type": "string",
                          "example": "USDC"
                        },
                        "amount_atomic": {
                          "type": "string",
                          "example": "550000",
                          "description": "USDC amount in atomic units (6 decimals)"
                        },
                        "price_usd": {
                          "type": "string",
                          "example": "0.55"
                        },
                        "pay_to": {
                          "type": "string",
                          "description": "receiver wallet address"
                        },
                        "resource": {
                          "type": "string",
                          "example": "POST /launches"
                        },
                        "resource_url": {
                          "type": "string",
                          "example": "https://api.dropspace.dev/launches",
                          "description": "canonical URL wallets sign EIP-712 against"
                        },
                        "max_timeout_seconds": {
                          "type": "integer",
                          "example": 300
                        }
                      }
                    },
                    "mpp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 1
                        },
                        "method": {
                          "type": "string",
                          "example": "stripe"
                        },
                        "intent": {
                          "type": "string",
                          "example": "charge"
                        },
                        "currency": {
                          "type": "string",
                          "example": "usd"
                        },
                        "amount_cents": {
                          "type": "integer",
                          "example": 60
                        },
                        "resource": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: persona not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "LAUNCH_002: plan launch limit reached; RATE_001: content generation rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "CONTENT_005: content safety check temporarily unavailable (transient: safe to retry with the same content)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "launch title"
                  },
                  "product_description": {
                    "type": "string",
                    "description": "product description: required for AI generation unless product_url, custom_content, or platform_contents is provided"
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "target platforms - can be omitted when dropspace_platforms or user_platform_accounts is provided (inferred from their union)"
                  },
                  "product_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "product URL: scraped to generate content; satisfies the description requirement on its own"
                  },
                  "track_links": {
                    "type": "boolean",
                    "description": "swap product_url in the post copy for a tracked dropspace.dev redirect on twitter, linkedin, facebook, reddit, and youtube (one link per posted item); clicks by people, not link-preview crawlers, appear as metrics.tracked_clicks in analytics. instagram, tiktok, and snapchat keep the plain URL. API-key launches only: x402 and MPP launches post to dropspace's official accounts and ignore it. default false"
                  },
                  "save_to_library": {
                    "type": "boolean",
                    "description": "add the launch's uploaded (non-AI) media_assets to the media library, where autopilot can post them. API-key launches only. default false"
                  },
                  "scheduled_date": {
                    "type": "string",
                    "format": "date-time",
                    "description": "schedule for future (≥ 15 min from now). any ISO 8601 offset works: `2026-12-01T12:00:00Z`, `…T12:00:00.000Z`, or `2026-12-01T08:00:00-04:00`"
                  },
                  "persona_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "writing style persona to use"
                  },
                  "dropspace_platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "post via dropspace official accounts: every auto-post platform except reddit (to post to reddit, target your own account with user_platform_accounts). published content begins with a \"posted from dropspace user:\" attribution line, inside the first tweet of a twitter thread (see attribution_mode)"
                  },
                  "attribution_mode": {
                    "type": "string",
                    "enum": [
                      "handle",
                      "anonymous"
                    ],
                    "description": "how official-account posts credit you: \"handle\" (default) signs with your connected @handle on that platform when you have one, \"anonymous\" always uses the plain note"
                  },
                  "user_platform_accounts": {
                    "type": "object",
                    "description": "map of platform key → token_id (UUID). most platforms use a simple key: \"twitter\", \"reddit\", \"instagram\", \"tiktok\", \"youtube\" (your primary/only account on that platform). to target a SPECIFIC account when you have more than one on the same platform, use a composite key: Instagram/TikTok/YouTube/Twitter/Reddit use \"instagram:<account_id>\" / \"tiktok:<account_id>\" / \"youtube:<account_id>\" / \"twitter:<account_id>\" / \"reddit:<account_id>\" (the account's entity_id from GET /connections); LinkedIn uses \"linkedin:personal\" or \"linkedin:organization:<org_id>\". a Facebook post goes to a PAGE: \"facebook:page:<page_id>\" names one (the page's entity_id from GET /connections), and a bare \"facebook\" key works when you have exactly one page - send a connection id as the value (the page's row or your own) and dropspace resolves the page; with several pages the request returns a 400 listing them. multiple keys allowed - e.g. post to two Instagram accounts, or personal + org - by listing several keys at once. for Reddit, each targeted account runs its own subreddit fan-out. an entry with an unsupported key, or a token id that isn't one of your connected accounts, returns a 400"
                  },
                  "media": {
                    "type": "array",
                    "description": "inline media upload - each item is either `{ source: \"url\", url: \"https://...\" }` to fetch from a URL, or `{ source: \"base64\", data: \"...\", filename: \"photo.jpg\", mime_type: \"image/jpeg\" }` for raw data. the server uploads to storage and populates media_assets automatically. mutually exclusive with media_assets. max 10 items (9 images + 1 video). images: jpeg, png, webp, gif (5MB). videos: mp4, mov (512MB via URL, 4MB via base64). when provided, media_attach_platforms and media_mode are auto-inferred if not set. **for videos >~50 MB, prefer pre-uploading to your own storage and passing `media_assets` instead: the inline `media` URL path runs inside the POST request lifecycle (bounded by the 5-min route maxDuration) and is sensitive to slow upstreams and Vercel function memory**. URL items share one ~270s total fetch budget and are fetched one at a time. a client that times out does not cancel the request - send an `Idempotency-Key` header (up to 255 characters of letters, digits, `.`, `_`, and `-`; anything else answers 400) so a retry cannot create a second launch"
                  },
                  "media_assets": {
                    "type": "array",
                    "description": "pre-uploaded media objects (id, url, type, filename, size, mime_type). mutually exclusive with media"
                  },
                  "media_attach_platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "platforms to attach media to (subset of platforms). auto-inferred from selected platforms when using media"
                  },
                  "media_mode": {
                    "type": "string",
                    "enum": [
                      "images",
                      "video"
                    ],
                    "description": "media mode for the launch. auto-inferred from media types when using media"
                  },
                  "platform_contents": {
                    "type": "object",
                    "description": "pre-written content per platform - each value needs `content` (string). for Twitter, you can alternatively provide `thread` (string[], each ≤ 280 chars or ≤ 25,000 for X Premium accounts, max 6 tweets) instead of `content` - mutually exclusive with `content`. Reddit requires `title` (string, max 300 chars) and supports an optional `metadata` object: `metadata.subreddits` (string[], max 10, names without the `r/` prefix) fans the launch out to one post per subreddit: each gets its own posting log, readable per-community via `GET /launches/:id/destinations` and retryable via `POST /launches/:id/retry` + `{ \"subreddit\": \"<name>\" }`; `metadata.first_comment` (string, max 1,500 chars) is posted as a comment under each Reddit post once it goes live. Product Hunt and Hacker News support an optional `title` field (max 60 and 80 chars respectively). TikTok supports a `tiktok_settings` object. `publish_mode` selects delivery: \"direct\" (default - publishes immediately to the profile) or \"draft\" (uploads to the TikTok inbox so the creator finishes editing and publishes in the TikTok app). for direct posts, `privacy_level` is required before publishing (\"PUBLIC_TO_EVERYONE\", \"FOLLOWER_OF_CREATOR\", \"MUTUAL_FOLLOW_FRIENDS\", or \"SELF_ONLY\"); in draft mode privacy is chosen in-app and `privacy_level` is not required. optional booleans (direct mode): `allow_comments`, `allow_duet`, `allow_stitch`, `is_commercial`, `is_your_brand`, `is_branded_content`, `auto_add_music`. `cover_timestamp_ms` (integer, 0-600000) picks the VIDEO cover frame in milliseconds from the start - video posts only, since photo posts take their cover by index; omit it for the first frame. when provided, AI content generation is skipped. per-platform character limits are enforced: Twitter 280/tweet (25,000 for X Premium) × 6 tweets, LinkedIn 3,000, Instagram 2,200, Reddit 3,000, Facebook 3,000, TikTok 4,000, YouTube 5,000 (description, title max 100), Product Hunt 500, Hacker News 2,000, Substack 3,000. YouTube requires video and supports an optional `title` field (max 100 chars) plus a `youtube_settings` object: `thumbnail_url` (https URL to a custom video thumbnail - applied after upload via the YouTube thumbnails.set API; requires a VERIFIED YouTube channel and is best-effort, so a thumbnail failure never fails the post), `privacy_status` (\"public\", \"unlisted\", or \"private\"), `category_id` (e.g. \"28\"), `tags` (string[]), `post_type` (\"auto\" | \"short\" | \"regular\" - auto-detects Shorts), `made_for_kids` (boolean), and `contains_synthetic_media` (boolean - the YouTube altered/synthetic content disclosure, required for realistic AI-generated or altered video). Instagram and Facebook each take a settings object for the 24-hour story surface: `instagram_settings` / `facebook_settings` with `post_type` (\"feed\" - the default - or \"story\"). Instagram alone takes a third `post_type`, \"carousel\": ONE carousel holding every attached image and the launch's video, in the order of your media, where \"feed\" would post the video as a reel and leave the images out. a carousel is 2 to 10 items (Instagram's limit) and a launch carries at most one video, so that is up to 9 images and a video; fewer than 2 or more than 10 fails validation. every other platform on the same launch still posts one media type. a fourth Instagram `post_type`, \"trial_reel\", posts the launch's video as a reel shown to non-followers first (Meta's trial reel): it is not on the profile or in followers' feeds until it graduates, by hand in the Instagram app (`graduation_strategy` \"MANUAL\", the default) or automatically when Instagram sees it performing well (\"SS_PERFORMANCE\"); dropspace sends Meta's own values and does not read back whether a reel has graduated. a trial reel needs a video and leaves photos out whatever `media_mode` says (a launch without a video fails validation before publishing), and an account Instagram lets post one: Instagram allows trial reels from professional (business or creator) accounts with 200 or more followers, so POST /launches and PATCH /launches/:id refuse the post type for a connected account below that bar, naming the account and its count (a stored count that says no is re-read from Instagram first); a trial reel Instagram itself refuses at publish fails on its own posting log with error_code \"NOT_ELIGIBLE\", never as an expired token, while the launch's other platforms post; the posting log's metadata carries `post_type: \"trial_reel\"` and `graduation_strategy`, and comments and analytics read a trial reel like any reel. a story publishes EVERY attached image as its own frame, in order (a video wins unless `media_mode` is \"images\"; a video pool publishes one frame per video), so five images give a five-frame story. each frame is a separate publish and a published story cannot be unpublished, so if a later frame fails the earlier ones stay live and the posting log records `story_frame_count` against `story_frames_requested`, with `story_frame_ids` listing them all - `post_id` and `post_url` point at the first frame. neither platform's API accepts a caption, text overlay, sticker, or link on a story, so `content` is ignored, and story posts read unsupported from GET /launches/:id/comments (viewers reply by direct message). instagram story analytics carry `views`, `reach` and `replies` while the story is live; Meta serves story insights only for 24 hours and withholds them entirely under 5 viewers, so an expired or low-view story reports no metrics rather than zeros. mutually exclusive with custom_content"
                  },
                  "custom_content": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    ],
                    "description": "single text distributed to all selected platforms, or array of tweet strings when twitter is selected. string form is validated against the most restrictive platform limit. array form creates a twitter thread (each ≤280 chars or ≤25,000 for X Premium, max 6) and consolidates for other platforms. mutually exclusive with platform_contents. when provided, AI content generation is skipped"
                  },
                  "custom_content_reddit_title": {
                    "type": "string",
                    "description": "reddit post title - required when using custom_content with reddit in platforms"
                  },
                  "publish": {
                    "type": "boolean",
                    "description": "immediately publish after creation. returns 202 instead of 201. mutually exclusive with scheduled_date. requires both `write` and `send` scopes (API key auth)."
                  },
                  "wait": {
                    "type": "boolean",
                    "description": "wait for publishing to complete and return post URLs inline (returns 200 with posting_status). requires publish: true. response includes posting_status with per-platform results. typical wait: 10-30s for text platforms (Twitter, LinkedIn, Reddit, Facebook), up to 60s+ with Instagram or TikTok"
                  }
                },
                "required": [
                  "title",
                  "platforms"
                ]
              }
            }
          }
        },
        "description": "the media field lets you upload images/videos inline via URL or base64 without pre-uploading to storage - the server handles upload and returns media_assets in the response\n\nmedia and media_assets are mutually exclusive - use media for inline upload, or media_assets if you've already uploaded files to storage\n\n**operational tip**: the inline `media` URL fetch runs inside the POST request (bound by the 5-min route maxDuration) and streams the body through to storage. for videos >~50 MB or slow source hosts, pre-uploading to your own storage and passing `media_assets` is more reliable: it lets the publish worker pull from a fast intra-region URL when it actually posts to the platform, instead of bottlenecking the create request\n\ncontent is generated automatically via Claude using your description, scraped website data, and persona style\n\ncustom_content and platform_contents are mutually exclusive - use one or the other (or neither for full AI generation)\n\nproduct_url is optional but enhances AI generation by providing scraped website data for additional context\n\nif platform_contents is provided, those platforms skip AI generation - only platforms without a truthy content field are generated\n\ncustom_content as a string distributes the same text to all platforms - validated against the lowest character limit. as an array (string[]), it creates a numbered twitter thread and joins tweets with double newlines for other platforms. array form requires twitter in platforms\n\npartial coverage is supported: provide content for some platforms and let AI generate the rest\n\nfor Twitter threads, use `platform_contents.twitter.thread: [\"tweet 1\", \"tweet 2\"]` instead of `content` - each tweet ≤ 280 chars (≤ 25,000 for X Premium accounts), max 6 tweets. mutually exclusive with `content`\n\nfor Reddit, `platform_contents.reddit.metadata.subreddits` (string[], max 10) posts the launch once per subreddit: each destination gets its own posting log, and posts are paced automatically to respect Reddit's shared rate limit. omit it to post to the default community. read the per-destination outcome from `GET /launches/:id/destinations` (it names the `subreddit` on each row - `GET /launches/:id/status` reports them all as the same `platform`), and retry one community with `POST /launches/:id/retry` + `{ \"subreddit\": \"<name>\" }`. **each subreddit has its own rules**: many restrict or ban promotional posts, some require flair, and posting where the account has no history gets filtered by AutoMod or the spam filter. prefer a few genuinely relevant subreddits over a broad blast; the web app surfaces per-community rules and account standing before posting\n\nfor Reddit multi-account, each connected reddit account can target its OWN subreddits: set `platform_contents[\"reddit:<account_id>\"].metadata.subreddits` for a specific account (falls back to the base `reddit` block). a subreddit is posted by at most ONE of your connected reddit accounts per launch - if two accounts list the same community, the first (primary first) posts it and the other is skipped with `SUBREDDIT_ALREADY_TARGETED`\n\nfor Reddit, `platform_contents.reddit.metadata.first_comment` (string, max 1,500 chars) posts a comment under each Reddit post once it is confirmed live - useful for the link or extra context when the post itself should stay native. a first-comment failure never affects the launch result\n\nmedia is distributed to selected platforms with per-platform limits (Instagram/Facebook: 10, Reddit: 20, TikTok: 35)\n\nInstagram requires at least one image, video, or AI-generated video. TikTok requires video or photos\n\nTikTok direct posts (`tiktok_settings.publish_mode: \"direct\"`, the default) require `tiktok_settings.privacy_level` to be set before publishing (TikTok Content Sharing Guidelines). set it at creation time via `platform_contents.tiktok.tiktok_settings` or update it later via PATCH. branded content (`is_branded_content: true`) cannot use SELF_ONLY privacy. with `publish_mode: \"draft\"` the post is uploaded to the creator's TikTok inbox to finish and publish in the TikTok app, so `privacy_level` is not required\n\nwhen `publish: true`, the launch is created and immediately queued for publishing - returns **202** instead of 201. if publish validation fails after creation, returns 201 with a `publish_error` field containing `{ code, message }` - retry via `POST /launches/:id/publish`\n\n`publish` and `scheduled_date` are mutually exclusive - use one or the other\n\n`publish: true` requires at least one posting account (`user_platform_accounts` or `dropspace_platforms`). with API key auth, both `write` and `send` scopes are required\n\n`wait: true` runs the publisher synchronously and returns 200 with `posting_status` containing per-platform results and post URLs. the request stays open until all platforms finish (typically 10-30s, up to 60s+ with Instagram/TikTok). if any platform fails, `posting_status` still shows successes - check `status` field per platform",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.550000"
          },
          "protocols": [
            {
              "x402": {}
            },
            {
              "mpp": {
                "method": "stripe",
                "intent": "charge",
                "currency": "usd"
              }
            }
          ]
        }
      }
    },
    "/launches/{id}": {
      "get": {
        "tags": [
          "launches"
        ],
        "summary": "get a single launch with posting status",
        "operationId": "getLaunch",
        "security": [
          {
            "apiKey": []
          },
          {
            "agentPaymentAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Launch"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "payment required: agent payment auth (x402 or MPP). launch creation beyond the free tier (5/month) costs $0.55 via x402 (crypto) or $0.60 via MPP (card). Authoritative x402 wallet challenge ships in the PAYMENT-REQUIRED header per x402 v2 spec; the body x402 block is a convenience for integrators inspecting JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "PAYMENT_001"
                        },
                        "message": {
                          "type": "string",
                          "example": "payment required: $0.55 USDC per launch (x402, 5 free/month) or $0.60 per launch (MPP)"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    },
                    "x402": {
                      "type": "object",
                      "description": "x402 protocol metadata (mirrors PAYMENT-REQUIRED header content)",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 2
                        },
                        "scheme": {
                          "type": "string",
                          "example": "exact"
                        },
                        "network": {
                          "type": "string",
                          "example": "base-mainnet"
                        },
                        "asset": {
                          "type": "string",
                          "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "description": "USDC contract address on Base"
                        },
                        "asset_name": {
                          "type": "string",
                          "example": "USDC"
                        },
                        "amount_atomic": {
                          "type": "string",
                          "example": "550000",
                          "description": "USDC amount in atomic units (6 decimals)"
                        },
                        "price_usd": {
                          "type": "string",
                          "example": "0.55"
                        },
                        "pay_to": {
                          "type": "string",
                          "description": "receiver wallet address"
                        },
                        "resource": {
                          "type": "string",
                          "example": "POST /launches"
                        },
                        "resource_url": {
                          "type": "string",
                          "example": "https://api.dropspace.dev/launches",
                          "description": "canonical URL wallets sign EIP-712 against"
                        },
                        "max_timeout_seconds": {
                          "type": "integer",
                          "example": 300
                        }
                      }
                    },
                    "mpp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 1
                        },
                        "method": {
                          "type": "string",
                          "example": "stripe"
                        },
                        "intent": {
                          "type": "string",
                          "example": "charge"
                        },
                        "currency": {
                          "type": "string",
                          "example": "usd"
                        },
                        "amount_cents": {
                          "type": "integer",
                          "example": 60
                        },
                        "resource": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      },
      "patch": {
        "tags": [
          "launches"
        ],
        "summary": "update a draft/scheduled/cancelled launch",
        "operationId": "updateLaunch",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Launch"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "UPLOAD_001: unsupported media type; UPLOAD_002: media file too large; UPLOAD_003: media storage upload failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "LAUNCH_003: cannot update a running, completed, or partial launch",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scheduled_date": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "schedule for future (≥ 15 min from now), null to unschedule. any ISO 8601 offset works: `2026-12-01T12:00:00Z` or `2026-12-01T08:00:00-04:00`"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "manual",
                      "trigger",
                      "scheduled",
                      "paused",
                      "cancelled"
                    ],
                    "description": "update launch status. \"paused\" holds a scheduled launch: it keeps its scheduled_date, is skipped by publishing, and stays paused through other edits. send \"scheduled\" to resume it; if its time has passed, send a new scheduled_date in the same request. only a scheduled launch can be paused. \"cancelled\" clears scheduled_date"
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "target platforms for this launch"
                  },
                  "name": {
                    "type": "string",
                    "description": "launch name/title (max 200 chars)"
                  },
                  "product_description": {
                    "type": "string",
                    "description": "product description (max 10,000 chars)"
                  },
                  "product_url": {
                    "type": "string",
                    "description": "product URL (empty string to clear)"
                  },
                  "persona_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "persona ID for content generation, null to clear"
                  },
                  "platform_contents": {
                    "type": "object",
                    "description": "per-platform content update (deep-merged with existing) - fields you include replace the old value, omitted fields are preserved. a `*_settings` object (`instagram_settings`, `tiktok_settings`, `youtube_settings`, `snapchat_settings`, `facebook_settings`) merges one level deeper, so one setting can be sent without the rest; every other value (a string, `images`, reddit `metadata`) replaces whole. for Twitter, you can use `thread` (string[], each ≤ 280 chars or ≤ 25,000 for X Premium, max 6) instead of `content` - mutually exclusive with `content`. Reddit `title` is optional (existing title preserved if omitted; max 300 chars if provided). Product Hunt and Hacker News support an optional `title` field (max 60 and 80 chars respectively). TikTok `tiktok_settings` can be set or updated here (deep-merged) - see POST docs for field details. per-platform character limits are enforced: Twitter 280/tweet (25,000 for X Premium) × 6 tweets, LinkedIn 3,000, Instagram 2,200, Reddit 3,000, Facebook 3,000, TikTok 4,000, YouTube 5,000 (description, title max 100), Product Hunt 500, Hacker News 2,000, Substack 3,000. YouTube `title` is optional on update (existing title preserved if omitted)"
                  },
                  "user_platform_accounts": {
                    "type": "object",
                    "description": "map of platform key → token_id (UUID). most platforms use a simple key: \"twitter\", \"reddit\", \"instagram\", \"tiktok\", \"youtube\" (your primary/only account on that platform). to target a SPECIFIC account when you have more than one on the same platform, use a composite key: Instagram/TikTok/YouTube/Twitter/Reddit use \"instagram:<account_id>\" / \"tiktok:<account_id>\" / \"youtube:<account_id>\" / \"twitter:<account_id>\" / \"reddit:<account_id>\" (the account's entity_id from GET /connections); LinkedIn uses \"linkedin:personal\" or \"linkedin:organization:<org_id>\". a Facebook post goes to a PAGE: \"facebook:page:<page_id>\" names one (the page's entity_id from GET /connections), and a bare \"facebook\" key works when you have exactly one page - send a connection id as the value (the page's row or your own) and dropspace resolves the page; with several pages the request returns a 400 listing them. multiple keys allowed - e.g. post to two Instagram accounts, or personal + org - by listing several keys at once. for Reddit, each targeted account runs its own subreddit fan-out. an entry with an unsupported key, or a token id that isn't one of your connected accounts, returns a 400"
                  },
                  "dropspace_platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "post via dropspace official accounts: every auto-post platform except reddit (to post to reddit, target your own account with user_platform_accounts). published content begins with a \"posted from dropspace user:\" attribution line, inside the first tweet of a twitter thread (see attribution_mode)"
                  },
                  "attribution_mode": {
                    "type": "string",
                    "enum": [
                      "handle",
                      "anonymous"
                    ],
                    "description": "how official-account posts credit you: \"handle\" (default) signs with your connected @handle on that platform when you have one, \"anonymous\" always uses the plain note"
                  },
                  "media": {
                    "type": "array",
                    "description": "inline media upload - same format as create. replaces existing media. mutually exclusive with media_assets"
                  },
                  "media_assets": {
                    "type": "array",
                    "description": "pre-uploaded media objects. replaces existing media. mutually exclusive with media"
                  },
                  "media_attach_platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "platforms to attach media to. auto-inferred when using media"
                  },
                  "media_mode": {
                    "type": "string",
                    "enum": [
                      "images",
                      "video"
                    ],
                    "description": "media mode. auto-inferred when using media"
                  }
                }
              }
            }
          }
        },
        "description": "all fields are optional but at least one must be provided\n\na running launch can only be updated to set status to cancelled\n\nunrecognized fields return a 400 error\n\nstatus is auto-derived for editable launches (draft, manual, trigger, scheduled). the server determines status based on your launch configuration: has posting accounts (user_platform_accounts or dropspace_platforms) + scheduled_date → scheduled. has posting accounts + no scheduled_date → trigger. has content + no posting accounts → manual. you cannot force \"manual\" on a launch with posting accounts. it will auto-transition to \"trigger\". to unschedule a launch, PATCH with { \"scheduled_date\": null }, status auto-becomes \"trigger\". to hold a scheduled launch without losing its date, PATCH with { \"status\": \"paused\" }: a paused launch is not auto-derived, is not published (POST /launches/{id}/publish refuses it), and stays paused until you PATCH { \"status\": \"scheduled\" }\n\nplatform_contents merges per platform - existing platforms not included in the update are preserved. within a platform, fields you include replace the old value\n\nfor Twitter threads, use `platform_contents.twitter.thread: [\"tweet 1\", \"tweet 2\"]` instead of `content` - each tweet ≤ 280 chars (≤ 25,000 for X Premium), max 6 tweets\n\nmedia and media_assets replace existing media entirely (no merging)\n\nTikTok `tiktok_settings` is deep-merged - you can update individual fields (e.g. only `privacy_level`) without overwriting the rest"
      },
      "delete": {
        "tags": [
          "launches"
        ],
        "summary": "delete a launch (any status except running)",
        "operationId": "deleteLaunch",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "204": {
            "description": "no content"
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "LAUNCH_003: cannot delete a launch that is currently running",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/launches/{id}/publish": {
      "post": {
        "tags": [
          "launches"
        ],
        "summary": "queue launch for publishing (async)",
        "operationId": "publishLaunch",
        "security": [
          {
            "apiKey": []
          },
          {
            "agentPaymentAuth": []
          }
        ],
        "responses": {
          "202": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/MessageResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "message": "publish queued"
                  }
                }
              }
            }
          },
          "400": {
            "description": "LAUNCH_007: platform requirements not met - see errors array for details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "payment required: agent payment auth (x402 or MPP). launch creation beyond the free tier (5/month) costs $0.55 via x402 (crypto) or $0.60 via MPP (card). Authoritative x402 wallet challenge ships in the PAYMENT-REQUIRED header per x402 v2 spec; the body x402 block is a convenience for integrators inspecting JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "PAYMENT_001"
                        },
                        "message": {
                          "type": "string",
                          "example": "payment required: $0.55 USDC per launch (x402, 5 free/month) or $0.60 per launch (MPP)"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    },
                    "x402": {
                      "type": "object",
                      "description": "x402 protocol metadata (mirrors PAYMENT-REQUIRED header content)",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 2
                        },
                        "scheme": {
                          "type": "string",
                          "example": "exact"
                        },
                        "network": {
                          "type": "string",
                          "example": "base-mainnet"
                        },
                        "asset": {
                          "type": "string",
                          "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "description": "USDC contract address on Base"
                        },
                        "asset_name": {
                          "type": "string",
                          "example": "USDC"
                        },
                        "amount_atomic": {
                          "type": "string",
                          "example": "550000",
                          "description": "USDC amount in atomic units (6 decimals)"
                        },
                        "price_usd": {
                          "type": "string",
                          "example": "0.55"
                        },
                        "pay_to": {
                          "type": "string",
                          "description": "receiver wallet address"
                        },
                        "resource": {
                          "type": "string",
                          "example": "POST /launches"
                        },
                        "resource_url": {
                          "type": "string",
                          "example": "https://api.dropspace.dev/launches",
                          "description": "canonical URL wallets sign EIP-712 against"
                        },
                        "max_timeout_seconds": {
                          "type": "integer",
                          "example": 300
                        }
                      }
                    },
                    "mpp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 1
                        },
                        "method": {
                          "type": "string",
                          "example": "stripe"
                        },
                        "intent": {
                          "type": "string",
                          "example": "charge"
                        },
                        "currency": {
                          "type": "string",
                          "example": "usd"
                        },
                        "amount_cents": {
                          "type": "integer",
                          "example": 60
                        },
                        "resource": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: plan restriction on own connected accounts (dropspace official accounts are always allowed)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "LAUNCH_004: launch is not in a publishable state or already publishing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "LAUNCH_007: launch has no platforms configured for posting",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "the launch transitions to running - poll /status or listen for launch.completed / launch.failed / post.deleted webhooks\n\nwhen validation fails (LAUNCH_007), the response includes a `details` array listing all issues that must be fixed before publishing\n\nplatform validation checks: character limits (all platforms), Reddit title ≤ 300 chars, Reddit video mode needs video (thumbnail auto-generated if not provided), Reddit image mode needs images, Instagram reel needs video, Instagram carousel needs ≥ 2 images, Instagram post_type \"carousel\" needs 2 to 10 images and videos combined, Instagram post_type \"trial_reel\" needs a video (photos are left out), TikTok requires privacy_level in tiktok_settings (unless publish_mode is \"draft\"), TikTok video mode needs video, TikTok photo mode needs images, YouTube requires video, YouTube title ≤ 100 chars, YouTube description ≤ 5,000 chars\n\n**video size**: per-platform limit is 512 MB. YouTube uploads stream chunked through the worker (memory-bounded). multi-platform launches that share the same video pre-download it once; for very large files (>~300 MB) prefer publishing to one platform at a time, since the pre-download buffer doubles peak memory until each poster releases its handle",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/launches/{id}/retry": {
      "post": {
        "tags": [
          "launches"
        ],
        "summary": "retry failed platforms only. optional body `{ \"subreddit\": \"<name>\" }` narrows the retry to that ONE Reddit destination (get names from `GET /launches/:id/destinations`), leaving sibling subreddits that already succeeded untouched; add `\"account_id\": \"<id>\"` alongside it to target a specific Reddit account when the launch posted from more than one; omit the body to retry every failed platform.",
        "operationId": "retryLaunch",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "202": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/GenerateContentResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "message": "retry queued",
                    "platforms": [
                      "reddit",
                      "tiktok"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "LAUNCH_003: no failed platforms to retry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "LAUNCH_004: launch is already running",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/launches/{id}/retry-content": {
      "post": {
        "tags": [
          "launches"
        ],
        "summary": "retry content generation for failed platforms",
        "operationId": "retryContent",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/RetryContentResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "retried": [
                      "twitter",
                      "reddit"
                    ],
                    "succeeded": [
                      "twitter"
                    ],
                    "still_failing": [
                      "reddit"
                    ],
                    "rate_limited": []
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: no failed platforms to retry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "LAUNCH_002: per-launch regeneration limit reached; RATE_001: content generation rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "filter to specific platforms"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/launches/{id}/generate-content": {
      "post": {
        "tags": [
          "launches"
        ],
        "summary": "regenerate AI content for all or specific platforms",
        "operationId": "generateContent",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/GenerateContentResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "name": "announcing our new feature",
                    "platform_contents": {
                      "twitter": {
                        "content": "1/ Fresh new thread..."
                      },
                      "linkedin": {
                        "content": "New version..."
                      }
                    }
                  },
                  "generation": {
                    "platforms_generated": [
                      "linkedin",
                      "twitter"
                    ],
                    "failures": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: no product_description or platforms",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "LAUNCH_003: launch is running/completed/partial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "RATE_001: content generation rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "SERVER_001: content generation unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "platforms to regenerate (defaults to all)"
                  },
                  "generate_video_scripts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "generate video scripts for these platforms"
                  },
                  "linkedin_version": {
                    "type": "string",
                    "enum": [
                      "personal",
                      "company"
                    ],
                    "description": "which LinkedIn voice to regenerate - personal profile or company page",
                    "default": "personal"
                  }
                }
              }
            }
          }
        },
        "description": "existing content for other platforms is preserved\n\nmedia, video sources, and generated videos are never overwritten"
      }
    },
    "/launches/{id}/status": {
      "get": {
        "tags": [
          "launches"
        ],
        "summary": "detailed posting logs per platform",
        "operationId": "getLaunchStatus",
        "security": [
          {
            "apiKey": []
          },
          {
            "agentPaymentAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/LaunchStatusDetail"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "launch_id": "uuid",
                    "launch_status": "completed",
                    "posting_logs": [
                      {
                        "id": "uuid",
                        "platform": "twitter",
                        "status": "success",
                        "post_url": "https://x.com/...",
                        "post_id": "string | null",
                        "error_message": "string | null",
                        "error_code": "string | null",
                        "attempt_count": 1,
                        "posted_at": "ISO 8601",
                        "created_at": "ISO 8601"
                      }
                    ]
                  }
                }
              }
            }
          },
          "402": {
            "description": "payment required: agent payment auth (x402 or MPP). launch creation beyond the free tier (5/month) costs $0.55 via x402 (crypto) or $0.60 via MPP (card). Authoritative x402 wallet challenge ships in the PAYMENT-REQUIRED header per x402 v2 spec; the body x402 block is a convenience for integrators inspecting JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "PAYMENT_001"
                        },
                        "message": {
                          "type": "string",
                          "example": "payment required: $0.55 USDC per launch (x402, 5 free/month) or $0.60 per launch (MPP)"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    },
                    "x402": {
                      "type": "object",
                      "description": "x402 protocol metadata (mirrors PAYMENT-REQUIRED header content)",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 2
                        },
                        "scheme": {
                          "type": "string",
                          "example": "exact"
                        },
                        "network": {
                          "type": "string",
                          "example": "base-mainnet"
                        },
                        "asset": {
                          "type": "string",
                          "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "description": "USDC contract address on Base"
                        },
                        "asset_name": {
                          "type": "string",
                          "example": "USDC"
                        },
                        "amount_atomic": {
                          "type": "string",
                          "example": "550000",
                          "description": "USDC amount in atomic units (6 decimals)"
                        },
                        "price_usd": {
                          "type": "string",
                          "example": "0.55"
                        },
                        "pay_to": {
                          "type": "string",
                          "description": "receiver wallet address"
                        },
                        "resource": {
                          "type": "string",
                          "example": "POST /launches"
                        },
                        "resource_url": {
                          "type": "string",
                          "example": "https://api.dropspace.dev/launches",
                          "description": "canonical URL wallets sign EIP-712 against"
                        },
                        "max_timeout_seconds": {
                          "type": "integer",
                          "example": 300
                        }
                      }
                    },
                    "mpp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 1
                        },
                        "method": {
                          "type": "string",
                          "example": "stripe"
                        },
                        "intent": {
                          "type": "string",
                          "example": "charge"
                        },
                        "currency": {
                          "type": "string",
                          "example": "usd"
                        },
                        "amount_cents": {
                          "type": "integer",
                          "example": 60
                        },
                        "resource": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "launch_status is \"completed\" when every destination posted, \"partial\" when some posted and some failed, and \"failed\" when none posted.\n\na platform in the launch's platforms that has no account to post from (no user_platform_accounts key for it and no dropspace official posting) gets a failed log with error_code \"NO_ACCOUNT\" instead of being skipped, so a launch that posted elsewhere reads \"partial\". when none of the platforms has an account, nothing is posted, no logs are written, and the launch is marked \"completed\" as ready for manual posting.\n\nerror_code is a stable machine-readable code for a failed log. see posting error codes in the error handling docs for the full list and what to do about each one.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/launches/{id}/destinations": {
      "get": {
        "tags": [
          "launches"
        ],
        "summary": "one row per destination, naming the account and subreddit. use this instead of /status when a launch fans out to several destinations on one platform (Reddit subreddits, LinkedIn personal+organization, Facebook pages): /status reports every one of them as the same `platform` with no way to tell which is which, and a failed destination has no post_url to infer it from. `subreddit` is the community name (Reddit fan-out rows only, null elsewhere); `account_type` identifies every destination. pair with `POST /launches/:id/retry` + `{ \"subreddit\": \"<name>\" }` to retry a single community.",
        "operationId": "getDestination",
        "security": [
          {
            "apiKey": []
          },
          {
            "agentPaymentAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LaunchDestination"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "posting_log_id": "uuid",
                      "platform": "reddit",
                      "account_type": "user:subreddit:webdev",
                      "subreddit": "webdev",
                      "status": "success",
                      "post_url": "https://reddit.com/r/webdev/comments/...",
                      "post_id": "string | null",
                      "error_message": "string | null",
                      "error_code": "string | null",
                      "attempt_count": 1,
                      "posted_at": "ISO 8601",
                      "created_at": "ISO 8601"
                    },
                    {
                      "posting_log_id": "uuid",
                      "platform": "reddit",
                      "account_type": "user:subreddit:SideProject",
                      "subreddit": "SideProject",
                      "status": "failed",
                      "post_url": null,
                      "post_id": null,
                      "error_message": "post removed by automod",
                      "error_code": "POST_REMOVED",
                      "attempt_count": 1,
                      "posted_at": null,
                      "created_at": "ISO 8601"
                    }
                  ]
                }
              }
            }
          },
          "402": {
            "description": "payment required: agent payment auth (x402 or MPP). launch creation beyond the free tier (5/month) costs $0.55 via x402 (crypto) or $0.60 via MPP (card). Authoritative x402 wallet challenge ships in the PAYMENT-REQUIRED header per x402 v2 spec; the body x402 block is a convenience for integrators inspecting JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "PAYMENT_001"
                        },
                        "message": {
                          "type": "string",
                          "example": "payment required: $0.55 USDC per launch (x402, 5 free/month) or $0.60 per launch (MPP)"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    },
                    "x402": {
                      "type": "object",
                      "description": "x402 protocol metadata (mirrors PAYMENT-REQUIRED header content)",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 2
                        },
                        "scheme": {
                          "type": "string",
                          "example": "exact"
                        },
                        "network": {
                          "type": "string",
                          "example": "base-mainnet"
                        },
                        "asset": {
                          "type": "string",
                          "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "description": "USDC contract address on Base"
                        },
                        "asset_name": {
                          "type": "string",
                          "example": "USDC"
                        },
                        "amount_atomic": {
                          "type": "string",
                          "example": "550000",
                          "description": "USDC amount in atomic units (6 decimals)"
                        },
                        "price_usd": {
                          "type": "string",
                          "example": "0.55"
                        },
                        "pay_to": {
                          "type": "string",
                          "description": "receiver wallet address"
                        },
                        "resource": {
                          "type": "string",
                          "example": "POST /launches"
                        },
                        "resource_url": {
                          "type": "string",
                          "example": "https://api.dropspace.dev/launches",
                          "description": "canonical URL wallets sign EIP-712 against"
                        },
                        "max_timeout_seconds": {
                          "type": "integer",
                          "example": 300
                        }
                      }
                    },
                    "mpp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 1
                        },
                        "method": {
                          "type": "string",
                          "example": "stripe"
                        },
                        "intent": {
                          "type": "string",
                          "example": "charge"
                        },
                        "currency": {
                          "type": "string",
                          "example": "usd"
                        },
                        "amount_cents": {
                          "type": "integer",
                          "example": 60
                        },
                        "resource": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/launches/{id}/analytics": {
      "get": {
        "tags": [
          "launches"
        ],
        "summary": "publishing analytics with per-post engagement metrics (live refresh)",
        "operationId": "getLaunchAnalytics",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/LaunchAnalytics"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "launch_id": "uuid",
                    "launch_name": "announcing our new feature",
                    "launch_status": "completed",
                    "summary": {
                      "total": 3,
                      "successful": 3,
                      "failed": 0,
                      "pending": 0
                    },
                    "fetched_at": "2026-02-22T10:00:00Z",
                    "next_refresh_at": "2026-02-22T10:05:00Z",
                    "platforms": [
                      {
                        "platform": "twitter",
                        "status": "success",
                        "post_url": "https://x.com/...",
                        "post_id": "1234567890",
                        "posted_at": "ISO 8601",
                        "cache_status": "refreshed",
                        "is_deleted": false,
                        "deleted_detected_at": null,
                        "deletion_reason": null,
                        "metrics": {
                          "likes": 42,
                          "retweets": 12,
                          "replies": 5,
                          "quotes": 2,
                          "bookmarks": 8,
                          "impressions": 1500,
                          "urlClicks": 23,
                          "profileClicks": 7,
                          "tracked_clicks": 19,
                          "fetched_at": "2026-02-22T10:00:00Z"
                        }
                      },
                      {
                        "platform": "reddit",
                        "status": "success",
                        "post_url": "https://reddit.com/...",
                        "post_id": "abc123",
                        "posted_at": "ISO 8601",
                        "cache_status": "fresh",
                        "is_deleted": false,
                        "deleted_detected_at": null,
                        "deletion_reason": null,
                        "metrics": {
                          "score": 156,
                          "upvotes": 200,
                          "upvoteRatio": 0.78,
                          "comments": 34,
                          "fetched_at": "2026-02-22T09:58:00Z"
                        }
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "metrics.tracked_clicks appears when the launch was created with track_links: clicks on its tracked link for that platform, counted on the platform's first post so summing posts never double-counts.\n\nmetrics refresh on a per-platform cycle. YouTube statistics are refreshed for you every 10 minutes in the background, so calling more often returns the same numbers from cache. other platforms are fetched live from their APIs when the cached copy is older than 5 minutes; calling this endpoint triggers that refresh automatically.\n\nfetched_at is the most recent timestamp when metrics were collected. next_refresh_at is the earliest time a call could return new numbers (fetched_at + 10 min for YouTube, + 5 min for other platforms) - polling before it only re-reads the cache.\n\ncache_status per platform: fresh (inside the refresh cycle, from cache), refreshed (fetched from platform API on this call), stale (rate limited or no token, returning older data), unavailable (no data exists). omitted for non-success posts (failed, pending).\n\nrate-limited platforms return stale cached data instead of failing - the response always includes the best available metrics.\n\nmetric fields vary by platform: Twitter (likes, retweets, replies, quotes, bookmarks, impressions, urlClicks, profileClicks), LinkedIn (impressions, uniqueImpressions, likes, comments, shares, clicks, engagement), Facebook (reactions, likes, comments, shares - likes mirrors reactions.total), Instagram (views, reach, engagement, saved, likes, comments, shares, totalInteractions; a reel adds avgWatchTimeMs, totalWatchTimeMs, and skipRate, the percent of plays that skipped in the first 3 seconds), Reddit (score, upvotes, upvoteRatio, comments), TikTok (views, likes, comments, shares)\n\nfacebook has no impressions or reach: those come from the platform's insights endpoint, which dropspace does not request. facebook story metrics are unavailable for the same reason - story insights are wired for instagram only.\n\na null metric means the platform did not disclose it, which is different from 0: youtube returns likes: null when the owner hides the like count and comments: null when comments are disabled.\n\nan instagram story reports views, reach, replies, and frames only while it is live: Meta serves story insights for 24 hours with no backfill. views and replies are summed across frames and reach is the widest single frame. views is null when Meta does not report it, and a story under 5 viewers returns story_insights_withheld: true instead of numbers (withheld, not zero).\n\nis_deleted indicates whether the post was detected as removed from the platform. when true, deleted_detected_at contains the detection timestamp and deletion_reason contains the reason. possible values: not_found (post no longer exists), gone (permanently removed, HTTP 410), creator_deleted (deleted by creator), moderation_removed (removed by moderation), account_deleted (account was deleted), spam_filtered (caught by spam filter). deletion is detected during metrics refresh."
      }
    },
    "/comments/queue": {
      "get": {
        "tags": [
          "launches"
        ],
        "summary": "every comment still waiting for you across your recent Instagram and YouTube posts, newest first, with a suggested action",
        "operationId": "listQueue",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CommentQueue"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "comments": [
                      {
                        "id": "18062216473153229",
                        "text": "what bpm do you start at for a set like this?",
                        "author_username": "djnova",
                        "author_display_name": "djnova",
                        "author_profile_image_url": null,
                        "like_count": 2,
                        "reply_count": 0,
                        "published_at": "2026-10-27T21:14:03.000Z",
                        "hidden": false,
                        "platform": "instagram",
                        "post_id": "18118432868104282",
                        "post_url": "https://www.instagram.com/reel/DfAJhNWDpoh/",
                        "launch_id": "8f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
                        "launch_name": "load the next track early",
                        "kind": "question",
                        "suggested_action": "reply",
                        "reply_draft": "I usually start around 122 and build from there. Try it and tell me how it feels.",
                        "may_be_answered": false
                      }
                    ],
                    "counts": {
                      "question": 1,
                      "feedback": 0,
                      "praise": 0,
                      "spam": 0,
                      "attack": 0,
                      "other": 0,
                      "unclassified": 0
                    },
                    "total_waiting": 1,
                    "posts_read": 30,
                    "posts_in_window": 112,
                    "post_issues": [],
                    "window_days": 30,
                    "as_of": "2026-10-28T22:00:00.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: partner creator paused or partner suspended",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "description": "reads up to 30 of your Instagram and YouTube posts made through dropspace in the last 30 days (the newest 50 comments on each) and returns up to 200 comments, newest first. When the window has more than 30 posts (posts_in_window), the ones with comments are read first, by the comment counts dropspace last read, newest first. total_waiting counts every waiting comment found; post_issues lists posts that could not be read (reconnect, quota) with why. Posts on dropspace's own accounts, stories, and posts made outside dropspace are not included.\n\nwaiting means: not hidden, not written by your account, not answered by your account (a reply from it, made in the app or here), and not replied to, hidden, deleted, or dismissed through dropspace.\n\nkind, suggested_action, and reply_draft are Claude's read of the comment text: questions and feedback suggest a reply (with a draft to edit), spam and attacks suggest hide, praise and other suggest dismiss. Each comment is sorted once and remembered; kind is null for comments not sorted yet (new ones are sorted up to 100 per load, 20 batches a day).\n\nmay_be_answered is true when YouTube returned only some of a comment's replies and none of those was yours: it stays in the queue, but you may have answered it already.\n\ncomment reads share the short page cache of GET /launches/{id}/comments, so a comment answered elsewhere can take about a minute to leave."
      }
    },
    "/comments/actions": {
      "post": {
        "tags": [
          "launches"
        ],
        "summary": "hide or dismiss up to 50 comments from the comment queue",
        "operationId": "createAction",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CommentActionsResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "action": "hide",
                    "succeeded": 1,
                    "failed": 1,
                    "results": [
                      {
                        "platform": "instagram",
                        "post_id": "18118432868104282",
                        "comment_id": "18062216473153229",
                        "ok": true,
                        "detail": null
                      },
                      {
                        "platform": "youtube",
                        "post_id": "dQw4w9WgXcQ",
                        "comment_id": "UgxKREWxIgDrw",
                        "ok": false,
                        "detail": "hiding comments is available for instagram only - not youtube"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: invalid json body, unknown action, or more than 50 comments",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: missing the send scope (hide) or write scope (dismiss), or partner creator paused",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "description": "hide (Instagram only, send scope) or dismiss (write scope): dismiss means seen, nothing to do; nothing changes on the platform"
                  },
                  "comments": {
                    "type": "array",
                    "description": "1-50 items of { platform, post_id, comment_id }, as GET /comments/queue returns them"
                  }
                },
                "required": [
                  "action",
                  "comments"
                ]
              }
            }
          }
        },
        "description": "only comments on your own posts made through dropspace are acted on; anything else, and hide on YouTube, comes back with ok: false and detail saying why.\n\nhides are sent one a second, so 50 take about a minute. Every item has its own result; the request does not stop at the first failure.\n\nto reply or delete one comment, use POST /launches/{id}/comments/replies and DELETE /launches/{id}/comments/{commentId} with the comment's launch_id and post_id; those also take it off the queue."
      }
    },
    "/launches/{id}/comments": {
      "get": {
        "tags": [
          "launches"
        ],
        "summary": "per-post comments for a launch's published posts (newest first)",
        "operationId": "getComment",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/LaunchComments"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "launch_id": "uuid",
                    "posts": [
                      {
                        "post_id": "dQw4w9WgXcQ",
                        "platform": "youtube",
                        "post_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
                        "posted_at": "ISO 8601",
                        "status": "ok",
                        "detail": null,
                        "comments": [
                          {
                            "id": "UgxKREWxIg...",
                            "text": "great launch!",
                            "author_username": "somefan",
                            "author_display_name": "@somefan",
                            "author_profile_image_url": "https://yt3.ggpht.com/...",
                            "like_count": 7,
                            "reply_count": 2,
                            "published_at": "ISO 8601"
                          }
                        ],
                        "next_cursor": "QURTSl9p..."
                      },
                      {
                        "post_id": "7301234567890",
                        "platform": "tiktok",
                        "post_url": "https://tiktok.com/...",
                        "posted_at": "ISO 8601",
                        "status": "unsupported",
                        "detail": "tiktok's api does not expose comment content to third-party apps - comment counts are available in analytics",
                        "comments": [],
                        "next_cursor": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: cursor without post_id, or invalid params",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          },
          {
            "name": "post_id",
            "in": "query",
            "required": false,
            "description": "read one post's comments only (required when paginating with cursor)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "only posts on this platform (e.g. youtube)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "opaque next_cursor from a previous page - paginates ONE post, so post_id is required with it",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "comments per post, 1-100 (default 25)",
            "schema": {
              "type": "number"
            }
          }
        ],
        "description": "comments are top-level only, ordered newest first, and cached for ~60 seconds per page.\n\nplatform support is explicit per post via status: ok (comments returned), unsupported (the platform's api does not expose comment content), comments_disabled (turned off on the post), post_deleted (post no longer exists), unavailable (transient: rate limited, quota, or account not connected - retry later). detail carries the human-readable reason for every non-ok status.\n\nyoutube and instagram return comment content. instagram connections made before 08/25/2026 read unsupported with a reconnect prompt until the creator reconnects instagram once; tiktok exposes comment counts only (see analytics).\n\nto page through one post's comments, pass post_id plus the next_cursor from the previous response. next_cursor is null on the last page."
      }
    },
    "/launches/{id}/comments/replies": {
      "post": {
        "tags": [
          "launches"
        ],
        "summary": "reply to a comment on one of the launch's published posts, as the account that published it. body: `{ \"post_id\": \"<platform post id>\", \"comment_id\": \"<comment id from GET comments>\", \"message\": \"<1-2,200 chars>\" }`. youtube and instagram only - other platforms, and instagram connections made before 08/25/2026 (reconnect instagram once to fix), answer 400 with a human-readable message. requires the send scope.",
        "operationId": "replyToComment",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CommentReply"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "reply_id": "UgzXK..."
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: platform can't accept the reply (detail in message)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found, or post_id not on this launch",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "reply_id is the platform's id for the created reply; null when the platform doesn't return one.\n\na successful reply invalidates the post's cached comment pages, so the next GET reflects it immediately."
      }
    },
    "/launches/{id}/comments/hide": {
      "post": {
        "tags": [
          "launches"
        ],
        "summary": "hide or unhide a comment on one of the launch's published posts, as the account that published it. body: `{ \"post_id\": \"<platform post id>\", \"comment_id\": \"<comment id from GET comments>\", \"hidden\": true | false }`. a hidden comment stays visible to its author and disappears for everyone else; `hidden: false` reverses it. instagram only - other platforms, stories, and instagram connections made before 08/25/2026 (reconnect instagram once to fix) answer 400 with a human-readable message. requires the send scope.",
        "operationId": "hideComment",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CommentModeration"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "comment_id": "17895695668004550",
                    "hidden": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: platform can't hide the comment (detail in message)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found, or post_id not on this launch",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "comments read back with `hidden: true` from GET /launches/:id/comments once hidden.\n\na successful change invalidates the post's cached comment pages, so the next GET reflects it immediately."
      }
    },
    "/launches/{id}/comments/{commentId}": {
      "delete": {
        "tags": [
          "launches"
        ],
        "summary": "permanently delete a comment on one of the launch's published posts, as the account that published it. pass `post_id` (the platform post id from GET comments) as a query parameter - comment ids are only meaningful per post. instagram only, and instagram lets only the media owner delete; other platforms, stories, and pre-08/25/2026 instagram connections answer 400 with a human-readable message. requires the send scope.",
        "operationId": "deleteComment",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CommentDeletion"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "comment_id": "17895695668004550",
                    "deleted": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: platform can't delete the comment (detail in message)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found, or post_id not on this launch",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          },
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "commentId"
          },
          {
            "name": "post_id",
            "in": "query",
            "required": true,
            "description": "the platform post id the comment lives on (from GET /launches/:id/comments)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "deletion is permanent - prefer hide when the comment may need to come back."
      }
    },
    "/launches/analytics": {
      "get": {
        "tags": [
          "launches"
        ],
        "summary": "batch analytics for multiple launches (cache-only, no live refresh)",
        "operationId": "getBatchLaunchAnalytics",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchLaunchAnalyticsResponse"
                },
                "example": {
                  "data": [
                    {
                      "launch_id": "uuid",
                      "launch_name": "announcing our new feature",
                      "launch_status": "completed",
                      "summary": {
                        "total": 3,
                        "successful": 2,
                        "failed": 1,
                        "pending": 0
                      },
                      "platforms": [
                        {
                          "platform": "twitter",
                          "status": "success",
                          "post_url": "https://x.com/...",
                          "post_id": "1234567890",
                          "posted_at": "ISO 8601",
                          "is_deleted": false,
                          "deleted_detected_at": null,
                          "deletion_reason": null,
                          "cache_status": "fresh",
                          "metrics": {
                            "likes": 42,
                            "retweets": 12,
                            "impressions": 1500,
                            "fetched_at": "2026-02-22T10:00:00Z"
                          }
                        }
                      ]
                    }
                  ],
                  "errors": [
                    {
                      "id": "invalid-uuid",
                      "error": {
                        "code": "LAUNCH_001",
                        "message": "launch not found"
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: ids parameter missing or empty; SERVER_002: more than 100 IDs provided; SERVER_005: all IDs have invalid UUID format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "description": "comma-separated launch UUIDs (max 100)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "returns cached analytics only - does NOT trigger a live refresh from platform APIs. use the single-launch endpoint GET /launches/:id/analytics to trigger a fresh fetch.\n\naccepts up to 100 launch IDs. duplicate IDs are deduplicated. counts as 1 rate limit hit.\n\nresponse includes partial results: valid launches in data[], invalid/not-found in errors[].\n\ncache_status per platform: fresh (< 5 min old), stale (older cached data), unavailable (no metrics exist). never returns refreshed (no live fetch). omitted for non-success posts (failed, pending).\n\nmetric fields vary by platform - same as single-launch analytics endpoint."
      }
    },
    "/launches/{id}/posts/{logId}": {
      "delete": {
        "tags": [
          "launches"
        ],
        "summary": "delete a single published post from its platform",
        "operationId": "deleteLaunchPost",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "DELETE_NOT_SUPPORTED: platform does not support API deletion (Instagram, TikTok) - returned in response body, not as HTTP error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found; SERVER_003: posting log not found or not deletable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          },
          {
            "name": "logId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "logId"
          }
        ],
        "description": "requires `write` scope on your API key (included in the default scope set)\n\nonly works for Twitter, Facebook, LinkedIn, and Reddit - Instagram and TikTok do not support API deletion\n\nthe posting log must have status 'success' and a valid post_id\n\nif the post was already deleted on the platform (404), it is treated as a successful deletion\n\non success, the posting log status is updated to 'deleted'\n\nlogId is the posting_log UUID from the /status endpoint"
      }
    },
    "/launches/{id}/posts": {
      "delete": {
        "tags": [
          "launches"
        ],
        "summary": "delete all published posts for a launch from their platforms",
        "operationId": "deleteLaunchPosts",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/DeletePostsResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "results": [
                      {
                        "success": true,
                        "platform": "twitter",
                        "post_id": "123",
                        "deleted_at": "ISO 8601"
                      },
                      {
                        "success": true,
                        "platform": "linkedin",
                        "post_id": "urn:li:share:456",
                        "deleted_at": "ISO 8601"
                      },
                      {
                        "success": false,
                        "platform": "instagram",
                        "post_id": "789",
                        "error": "platform does not support deletion",
                        "error_code": "DELETE_NOT_SUPPORTED"
                      }
                    ],
                    "no_failures": false,
                    "deleted_count": 2,
                    "failed_count": 0,
                    "skipped_count": 1
                  }
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "requires `write` scope on your API key (included in the default scope set)\n\nonly deletes from Twitter, Facebook, LinkedIn, and Reddit\n\nInstagram and TikTok posts are skipped with DELETE_NOT_SUPPORTED (require manual deletion)\n\nreturns detailed results per post including success/failure status\n\nskipped_count includes platforms that don't support API deletion"
      }
    },
    "/audience": {
      "get": {
        "tags": [
          "audience"
        ],
        "summary": "follower counts + growth over a window for the caller's connected instagram/youtube/tiktok/twitter/facebook accounts",
        "operationId": "getAudience",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Audience"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "platforms": [
                      {
                        "platform": "instagram",
                        "entity_id": null,
                        "current": {
                          "followers": 10432,
                          "following": 812,
                          "media": 340,
                          "captured_at": "2026-07-22T06:00:00Z"
                        },
                        "series": [
                          {
                            "captured_at": "2026-06-22T06:00:00Z",
                            "followers": 9800
                          },
                          {
                            "captured_at": "2026-07-22T06:00:00Z",
                            "followers": 10432
                          }
                        ],
                        "growth": {
                          "window_days": 30,
                          "follower_delta": 632,
                          "follower_pct": 0.0645,
                          "baseline_captured_at": "2026-06-22T06:00:00Z",
                          "effective_window_days": 30
                        }
                      }
                    ],
                    "as_of": "2026-07-22T18:00:00Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "window_days",
            "in": "query",
            "required": false,
            "description": "growth window in days (default 30, max 365)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "instagram_insights adds Instagram growth analytics to each Instagram entry: follows and unfollows per day, estimated followers over time, weekly growth velocity, the share of reach from non-followers, and contact-button taps. Days are Pacific time and the last 7 are still revised by Instagram (settled: false). Read on request and stored, newest days first, up to 31 days per call: a longer window fills over a few calls (days_pending says how many are left). Accounts under 100 followers get available: false.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "covers instagram, youtube, tiktok, twitter, and facebook - the platforms whose follower counts the official apis expose. other connected platforms (linkedin, reddit) are omitted.\n\nfacebook follower counts are reported per connected page (each page reports its own followers); twitter reports followers, following, and tweet count.\n\ncounts are read on-demand when you call this endpoint and cached for 15 minutes. youtube is the exception, because each youtube read spends a shared daily quota: while you keep reading an account, its youtube count is refreshed in the background about once an hour, and an on-demand read re-fetches at most every 6 hours if that refresh is delayed. each fresh read records a history point - so a newly connected account appears on its first call and builds growth history from there.\n\ngrowth is computed from the earliest and latest snapshot inside the window; follower_pct is a fraction (0.0645 = 6.45%). delta and pct are null until at least one snapshot exists in the window.\n\nhistory points are recorded when you read (at most one per account per day), so the oldest point inside the window can be much younger than window_days. baseline_captured_at is when the delta is measured from, and effective_window_days is the span it actually covers - read it before comparing growth across accounts.\n\nyoutube history points are kept for 30 days (YouTube's API storage limit), so youtube growth reaches back about 30 days even when window_days is larger; effective_window_days says how far it actually reaches. other platforms keep their full history.\n\ncurrent.captured_at is when the returned count was actually read from the platform, never when it was served: a cached or background-refreshed count keeps its original read time, a youtube count returned while youtube's daily quota is exhausted carries the time of the last successful read, and if the platform call fails with nothing cached it is when the newest stored point was captured.\n\ndata collection uses each platform's official read api, not scraping - so it only covers accounts the creator has connected.\n\ninclude=instagram_insights adds instagram_insights to each instagram entry. days[] has follows, unfollows (accounts that unfollowed or left Instagram), net, and reach split into reach_followers and reach_non_followers, per Pacific-time day. followers_over_time is an estimate: the current count minus each later day's net. velocity compares the last 7 days' net, as a share of the count at the start of that week, with the average of the earlier full weeks in the window. non_follower_reach_share sums daily reach, so an account reached on two days counts twice. profile_links_taps covers the last 30 days of the window at most. Instagram reports none of this for accounts under 100 followers: available is false with unavailable_reason."
      }
    },
    "/audience/demographics": {
      "get": {
        "tags": [
          "audience"
        ],
        "summary": "who your Instagram audience is: age, gender, country, and city of your followers and of the accounts that engaged with you",
        "operationId": "listDemographics",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/AudienceDemographics"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "timeframe": "this_month",
                    "accounts": [
                      {
                        "connection_id": "3b9c1f0e-2d4a-4e8b-9c7d-6f5e4d3c2b1a",
                        "entity_id": null,
                        "username": "spin.sensei.app",
                        "followers": {
                          "available": true,
                          "unavailable_reason": null,
                          "age": [
                            {
                              "value": "25-34",
                              "count": 100
                            },
                            {
                              "value": "35-44",
                              "count": 70
                            },
                            {
                              "value": "45-54",
                              "count": 38
                            }
                          ],
                          "gender": [
                            {
                              "value": "M",
                              "count": 213
                            },
                            {
                              "value": "U",
                              "count": 27
                            },
                            {
                              "value": "F",
                              "count": 21
                            }
                          ],
                          "country": [
                            {
                              "value": "US",
                              "count": 49
                            },
                            {
                              "value": "IN",
                              "count": 29
                            },
                            {
                              "value": "IR",
                              "count": 16
                            }
                          ],
                          "city": [
                            {
                              "value": "New York, New York",
                              "count": 16
                            },
                            {
                              "value": "Bangalore, Karnataka",
                              "count": 7
                            }
                          ],
                          "total": 261
                        },
                        "engaged": {
                          "available": true,
                          "unavailable_reason": null,
                          "age": [
                            {
                              "value": "25-34",
                              "count": 196
                            },
                            {
                              "value": "18-24",
                              "count": 172
                            },
                            {
                              "value": "13-17",
                              "count": 38
                            }
                          ],
                          "gender": [
                            {
                              "value": "M",
                              "count": 379
                            },
                            {
                              "value": "U",
                              "count": 84
                            },
                            {
                              "value": "F",
                              "count": 36
                            }
                          ],
                          "country": [
                            {
                              "value": "US",
                              "count": 70
                            },
                            {
                              "value": "IN",
                              "count": 56
                            },
                            {
                              "value": "GB",
                              "count": 32
                            }
                          ],
                          "city": [
                            {
                              "value": "London, England",
                              "count": 7
                            },
                            {
                              "value": "Sydney, New South Wales",
                              "count": 2
                            }
                          ],
                          "total": 499
                        }
                      }
                    ],
                    "as_of": "2026-10-27T22:00:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: timeframe is not this_week, this_month, or last_90_days",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: partner creator paused or partner suspended",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "timeframe",
            "in": "query",
            "required": false,
            "description": "period for the engaged audience: this_week, this_month (default), or last_90_days. Followers are always the current followers. Any other value returns 400.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "followers describes the account's current followers; engaged describes the accounts that engaged with its content in timeframe. Each split (age, gender, country, city) is largest first. The example is shortened; a full answer has every age range and up to 45 countries and cities.\n\ngender values are F, M, and U (unknown); country is an ISO 3166-1 alpha-2 code; city is \"City, Region\". total is the number of people Instagram has demographic data for (the gender split's sum), which can be lower than the follower count.\n\nInstagram reports only the top 45 rows of a split and nothing for accounts under 100 followers: a section then has available: false with unavailable_reason. An engaged section can also be unavailable when too few accounts engaged in the period, and a single split (often city) comes back empty when it has too few people to report.\n\ncached about 12 hours per account and period; a failed Instagram read is asked again after 30 minutes, and unavailable_reason says what happened (reconnect the account for an expired token)."
      }
    },
    "/audience/best-hours": {
      "get": {
        "tags": [
          "audience"
        ],
        "summary": "when your Instagram followers are online: the average per hour and per weekday and hour over the last 30 days, and the busiest hours",
        "operationId": "listBestHours",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/BestPostingHours"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "timezone": "America/New_York",
                    "accounts": [
                      {
                        "connection_id": "3b9c1f0e-2d4a-4e8b-9c7d-6f5e4d3c2b1a",
                        "entity_id": null,
                        "username": "spin.sensei.app",
                        "available": true,
                        "unavailable_reason": null,
                        "days_counted": 28,
                        "hourly": [
                          76.4,
                          81.6,
                          87.4,
                          89.9,
                          91,
                          97.5,
                          100.6,
                          106.2,
                          108.4,
                          110.9,
                          117.1,
                          119.3,
                          117.1,
                          118,
                          113.3,
                          108.9,
                          101.6,
                          91.4,
                          82.4,
                          74.6,
                          70.1,
                          68.4,
                          65.4,
                          70.9
                        ],
                        "grid": [
                          [
                            78,
                            88,
                            93.3,
                            98.8,
                            96.8,
                            108.5,
                            116.3,
                            117.8,
                            117.5,
                            118.8,
                            127.3,
                            131.3,
                            129.5,
                            126,
                            125.8,
                            119,
                            110,
                            100,
                            86.5,
                            81.5,
                            77.3,
                            77.5,
                            72.5,
                            74.5
                          ],
                          [
                            82.5,
                            85.5,
                            87.8,
                            89.8,
                            88.5,
                            99.3,
                            99.3,
                            99.5,
                            108.8,
                            113.8,
                            115,
                            115.8,
                            114.5,
                            116,
                            110.8,
                            106.3,
                            98.8,
                            81.8,
                            75.5,
                            66.8,
                            60.5,
                            66.3,
                            62.5,
                            66
                          ],
                          [
                            79,
                            85.5,
                            88,
                            86.8,
                            87.5,
                            95.5,
                            97.3,
                            107.8,
                            106.3,
                            110,
                            112.3,
                            117,
                            112,
                            112.5,
                            108.3,
                            102.8,
                            100.3,
                            90.3,
                            79.5,
                            73.3,
                            69.3,
                            67.3,
                            62.8,
                            75.5
                          ],
                          [
                            78.5,
                            84.5,
                            89.8,
                            88.3,
                            91.5,
                            94.8,
                            98,
                            100.5,
                            108.3,
                            108,
                            121.3,
                            118.8,
                            112,
                            115.3,
                            106.8,
                            101.5,
                            97.5,
                            88.5,
                            76.3,
                            76,
                            74,
                            68.5,
                            64.8,
                            65.8
                          ],
                          [
                            72.3,
                            81,
                            82.3,
                            84.3,
                            85,
                            95.3,
                            101.5,
                            108.3,
                            109,
                            114.8,
                            119,
                            115.3,
                            114.5,
                            117.8,
                            111.5,
                            107.8,
                            102.3,
                            93,
                            84.8,
                            76.5,
                            67.3,
                            64.3,
                            63.3,
                            66.8
                          ],
                          [
                            72.3,
                            70.3,
                            85.3,
                            92,
                            92,
                            94.8,
                            92.8,
                            103,
                            103.5,
                            105.5,
                            106.3,
                            116.5,
                            113.3,
                            118.5,
                            111.3,
                            112,
                            98,
                            89.3,
                            85,
                            74.8,
                            71,
                            70,
                            66.8,
                            70.5
                          ],
                          [
                            72.3,
                            76.8,
                            85.5,
                            89.8,
                            96,
                            94.5,
                            99,
                            106.5,
                            105.8,
                            105.5,
                            118.8,
                            120.5,
                            124.3,
                            119.8,
                            118.5,
                            113.3,
                            104.8,
                            97,
                            89.5,
                            73.5,
                            71.3,
                            65.3,
                            65,
                            77.3
                          ]
                        ],
                        "best_hours": [
                          {
                            "hour": 11,
                            "avg_online": 119.3
                          },
                          {
                            "hour": 13,
                            "avg_online": 118
                          },
                          {
                            "hour": 9,
                            "avg_online": 110.9
                          }
                        ]
                      }
                    ],
                    "best_hours": [
                      {
                        "hour": 11,
                        "avg_online": 119.3
                      },
                      {
                        "hour": 13,
                        "avg_online": 118
                      },
                      {
                        "hour": 9,
                        "avg_online": 110.9
                      }
                    ],
                    "as_of": "2026-10-27T22:00:00Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: timezone is not an IANA timezone",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: partner creator paused or partner suspended",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "timezone",
            "in": "query",
            "required": false,
            "description": "IANA timezone every hour in the answer is expressed in, e.g. America/New_York. Default: your autopilot timezone, else UTC. The answer's timezone is the canonical name. An unknown zone returns 400.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "read from Instagram's online_followers insight for the last 30 days, through yesterday. days_counted is how many of those days Instagram returned hourly numbers for.\n\nhourly[h] is the average followers online in hour h (0-23) of the day; grid[d][h] is the same for weekday d (0 = sunday). Both are in timezone; null means no sample for that slot.\n\nbest_hours lists the busiest hours, busiest first, each at least two hours from the others (up to 5). The top-level best_hours sums every connected Instagram account's averages.\n\ncached about 12 hours per account. Instagram reports this only for accounts with 100 or more followers: available is false with unavailable_reason otherwise. When Instagram refuses or fails the read, unavailable_reason says so (reconnect the account for an expired token), and it is asked again after 30 minutes.\n\nto post at these hours, set posting_times with PATCH /autopilot (times are HH:MM in the autopilot timezone)."
      }
    },
    "/analytics/reels-read": {
      "get": {
        "tags": [
          "audience"
        ],
        "summary": "each connected Instagram account with its latest reels read (pro and premium)",
        "operationId": "listReelsRead",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/ReelsReadOverview"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "accounts": [
                      {
                        "connection_id": "3b9c1f0e-2d4a-4e8b-9c7d-6f5e4d3c2b1a",
                        "username": "spin.sensei.app",
                        "next_refresh_at": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: plan without reels reads (pro and premium have them), or partner creator paused",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "description": "returns stored reads only and makes no Instagram or Claude request. read is absent when no read was made for the account in the last 30 days; next_refresh_at is when POST can make a new one (null when it can now). The read object has the same shape as POST's."
      },
      "post": {
        "tags": [
          "audience"
        ],
        "summary": "Claude's read of an Instagram account's recent reels: what the top, middle, and bottom reels by views have in common (pro and premium)",
        "operationId": "createReelsRead",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/ReelsReadResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "status": "ok",
                    "read": {
                      "connection_id": "3b9c1f0e-2d4a-4e8b-9c7d-6f5e4d3c2b1a",
                      "username": "spin.sensei.app",
                      "generated_at": "2026-10-28T19:55:55.883Z",
                      "window_days": 90,
                      "reel_count": 60,
                      "oldest_posted_at": "2026-10-13T16:02:11+0000",
                      "tiers": {
                        "top": [
                          {
                            "id": "18145276189580095",
                            "permalink": "https://www.instagram.com/reel/Deb-7VZEacG/",
                            "posted_at": "2026-10-13T14:06:28+0000",
                            "caption": "when two kicks start drifting, guessing which way to nudge u",
                            "views": 2150,
                            "reach": 1664,
                            "likes": 33,
                            "comments": 1,
                            "shares": 1,
                            "saves": 13,
                            "avg_watch_time_ms": 17838,
                            "skip_rate": 40.3
                          }
                        ],
                        "middle": [
                          {
                            "id": "17939836590379472",
                            "permalink": "https://www.instagram.com/reel/DeejdIlD4Qo/",
                            "posted_at": "2026-10-14T14:04:10+0000",
                            "caption": "two vocals at once actually wreck a blend faster than almost",
                            "views": 229,
                            "reach": 194,
                            "likes": 4,
                            "comments": 0,
                            "shares": 1,
                            "saves": 0,
                            "avg_watch_time_ms": 7006,
                            "skip_rate": 49.5
                          }
                        ],
                        "bottom": [
                          {
                            "id": "17973853455158302",
                            "permalink": "https://www.instagram.com/reel/DerZkm7DrIM/",
                            "posted_at": "2026-10-19T13:47:55+0000",
                            "caption": "each new track gets pitched up to match the one before it, n",
                            "views": 161,
                            "reach": 139,
                            "likes": 0,
                            "comments": 0,
                            "shares": 1,
                            "saves": 0,
                            "avg_watch_time_ms": 5438,
                            "skip_rate": 69.8
                          }
                        ]
                      },
                      "read": {
                        "summary": "Your top reels hold viewers far longer than the rest, averaging 10.7s to 20.4s of watch time against mostly 4s to 10s for the middle and bottom. The same caption shows up in both your top and bottom groups, so the caption text alone does not explain the gap. Whatever happens in the first seconds of the video, which these numbers cannot show, seems to matter more.",
                        "working": [
                          {
                            "pattern": "Low early skips and longer watch time go with your highest views.",
                            "evidence": "Your top 10 all have avg watch of 10.7s or more and 3-second skip rates between 30.9% and 50.4%, for example 10-26 'if you wait until the last minute' at 20.4s and 35.6%, and 10-22 with the same caption at 19.4s and 30.9%. Most bottom reels sit at 4.1s to 10.2s with skips up to 73.5% (10-27 'wait to hear the one': 4.1s, 73.5%, 151 views)."
                          }
                        ],
                        "not_working": [
                          {
                            "pattern": "The same caption can land in your top or your bottom, so the difference is outside the caption.",
                            "evidence": "'test nudge' got 2150 views and 1915 views (10-13, 10-26) but only 158 and 146 views on 10-28, with skip rates rising from 40.3% to 51.6%. The 'rising whoosh' filter caption got 1578 views and 135 views on the same day, 10-25, with skips of 38% vs 50.5%."
                          }
                        ],
                        "next": [
                          "Pull up the 10-13 'test nudge' reel (40.3% skips) and the 10-28 version (51.6% skips) side by side. Note what differs in the first 3 seconds, then reuse the opening of the stronger one on your next two reels.",
                          "Make two more tempo-reading reels in the style of the 10-25 bpm counting tip (27 saves) and the 10-18 half-tempo tip (20.2s avg watch). Track whether saves stay above 10.",
                          "Stop posting the same caption twice on one day. Space repeats at least a week apart and compare each repeat's 3-second skip rate with the original."
                        ]
                      },
                      "model": "claude-opus-5-5"
                    },
                    "refreshed": true,
                    "next_refresh_at": "2026-10-29T15:00:00.000Z",
                    "reel_count": null,
                    "needed": null,
                    "reason": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: invalid json body, or connection_id is not a uuid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: plan without reels reads (pro and premium have them), or partner creator paused",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "connection_id": {
                    "type": "string",
                    "description": "the Instagram connection to read (from GET /analytics/reels-read or GET /connections); default: the first connected Instagram account"
                  }
                }
              }
            }
          }
        },
        "description": "connection_id is optional: without it, the first connected Instagram account is read. The body can be empty.\n\nreads the latest reels (up to 60) posted in the last 90 days, with their views, reach, likes, comments, shares, saves, avg watch time, and 3-second skip rate, ranks them by views, and sends the top, middle (around the median), and bottom ten, with captions, to Claude. A very active account's 60 reels can cover less than 90 days; oldest_posted_at says how far back the read reaches. Reels whose numbers Instagram did not return are left out; when more than a fifth are missing, the read is not made (status unavailable). The example is shortened to one reel per tier and one finding per list.\n\nClaude sees captions and numbers only, never the videos, and is told to say when the numbers show no clear pattern. working has 2 to 4 findings, not_working 1 to 3, next exactly 3.\n\nstatus ok: read is present (it is omitted for the other statuses). Each account gets 3 paid attempts a day, failed ones included; after that status is unavailable until tomorrow. refreshed is false when a read made in the last 24 hours was returned instead of a new one (one new read per account a day). status not_enough_reels: fewer than needed (8) reels in the window, with reel_count. status unavailable: reason says why (no Instagram account, reconnect, Instagram or Claude failed, a read already running).\n\ntakes 30 to 60 seconds. Reads are kept 30 days and returned by GET."
      }
    },
    "/analytics/trial-reels": {
      "get": {
        "tags": [
          "audience"
        ],
        "summary": "Instagram trial reel results: totals across every trial reel you posted through dropspace, one entry per reel, and net followers since the first one",
        "operationId": "listTrialReels",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TrialReelSummary"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "totals": {
                      "trial_reels": 9,
                      "views": 8012,
                      "reach": 6140,
                      "likes": 142,
                      "comments": 0,
                      "shares": 13,
                      "saves": 59,
                      "avg_watch_time_ms": 3660,
                      "skip_rate": 64.2
                    },
                    "followers_since_first": {
                      "net": 33,
                      "since_day": "2026-10-23",
                      "days_counted": 4,
                      "days_in_span": 4
                    },
                    "reels": [
                      {
                        "launch_id": "8f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
                        "launch_name": "verci boiler room v4 02",
                        "post_id": "18118432868104282",
                        "post_url": "https://www.instagram.com/reel/DfAJhNWDpoh/",
                        "posted_at": "2026-10-27T15:45:12Z",
                        "graduation_strategy": "MANUAL",
                        "views": 1912,
                        "reach": 1650,
                        "likes": 31,
                        "comments": 0,
                        "shares": 4,
                        "saves": 12,
                        "avg_watch_time_ms": 3660,
                        "skip_rate": 72.9,
                        "metrics_fetched_at": "2026-10-27T21:00:00Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: partner creator paused or partner suspended",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "description": "covers launches whose instagram_settings.post_type was trial_reel and whose Instagram post succeeded, newest first; reels lists up to 100, totals cover every one.\n\nreads stored numbers only and makes no Instagram request, so it can be polled. each reel's numbers are the ones last read from Instagram (metrics_fetched_at): the metrics sweep refreshes recent posts, and GET /launches/{id}/analytics refreshes one launch.\n\nreach is summed per reel, so an account reached by two reels counts twice. avg_watch_time_ms (milliseconds per play) and skip_rate (percent of plays that skipped in the first 3 seconds) are views-weighted across reels that report them, and null when none do.\n\nfollowers_since_first.net is follows minus unfollows on your Instagram accounts from the Pacific day of the first trial reel through yesterday, from the daily counts GET /audience?include=instagram_insights stores. days_counted says how many of days_in_span had a stored count; net is null when none did. it is every new follower in that span, not only ones the trial reels brought."
      }
    },
    "/trial-reels": {
      "get": {
        "tags": [
          "trial reels"
        ],
        "summary": "every connected Instagram account with its trial reel program, the hours it posts at, and its reshared reels",
        "operationId": "getTrialReelPrograms",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TrialReelPrograms"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "accounts": [
                      {
                        "connection_id": "3b8f6a1e-2c4d-4e5f-8a9b-0c1d2e3f4a5b",
                        "username": "spin.sensei.app",
                        "eligible": true,
                        "ineligible_reason": null,
                        "program": {
                          "id": "9d2e7c4a-1b3f-4a5e-8c6d-7e8f9a0b1c2d",
                          "enabled": true,
                          "auto_approve": false,
                          "reels_per_day": 1,
                          "skip_caption_terms": [
                            "giveaway"
                          ],
                          "timezone": "America/New_York",
                          "edit_kinds": [
                            "reshare",
                            "background"
                          ],
                          "last_scan_at": "2026-10-29T14:02:11.000Z",
                          "last_run_at": "2026-10-29T19:05:02.000Z",
                          "last_note": "posted a trial reel this hour"
                        },
                        "posting_hours": [
                          19
                        ],
                        "items": [
                          {
                            "id": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c",
                            "status": "posted",
                            "kind": "background",
                            "prepare_status": "ready",
                            "prepare_error": null,
                            "variant_url": "https://<project>.supabase.co/storage/v1/object/public/generated-media/<user>/trial-reels/<item>/background-1.mp4",
                            "edit_summary": null,
                            "approved": true,
                            "reason": "1,933 views, 2.4x your median of 806",
                            "caption": "load the next track early",
                            "source": {
                              "media_id": "18118432868104282",
                              "permalink": "https://www.instagram.com/reel/DfAJhNWDpoh/",
                              "caption": "load the next track early @djnova",
                              "views": 1933,
                              "posted_at": "2026-08-30T18:12:00.000Z"
                            },
                            "win_target": 967,
                            "launch_id": "8f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
                            "post_id": "18062216473153229",
                            "post_url": "https://www.instagram.com/reel/DgB1x2Yz3Ab/",
                            "claimed_at": "2026-10-29T19:05:01.000Z",
                            "posted_at": "2026-10-29T19:06:40.000Z",
                            "checkpoints": {},
                            "outcome_at": null,
                            "failure": null,
                            "created_at": "2026-10-29T14:02:11.000Z"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: not on the pro or premium plan, or partner creator paused",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "description": "program is absent until the account's program is first saved. eligible is false (with Instagram's rule in ineligible_reason) for personal accounts and accounts under 200 followers: Instagram refuses trial reels from them.\n\nposting_hours are hours of the day (0-23) in the program's timezone: the account's best hours from Instagram's followers-online numbers (GET /audience/best-hours), else 9, 13, and 18 when Instagram has none (under 100 followers). One reel per posting hour. On a day a posting hour passes without a post (another post was too close), a later one of the account's best hours that day is used instead, still up to reels_per_day.\n\nitems are the newest 100 that are not removed. status: queued (waiting; posts only once approved), posting (a launch was made, waiting for Instagram), posted (live as a trial reel, being checked), won, retired (no win by day 7, or deleted on Instagram), failed (failure says why).\n\nkind is reshare (the original video, as posted) or an edited version: background (the reel scaled onto a colored background), subtitles (word-timed subtitles burned in; only for reels with speech and no captions already on screen, otherwise the item fails with that reason), hook (Claude picks the strongest line from later in the reel, which plays first, then the whole reel; refused when no line would open it better), or sticker (a reply-to-comment card near the top; Claude writes the comment and a first-name commenter, so it is not a real viewer's comment). edit_summary says what an edit adds once known: the sticker's comment or the hook's opening line. An edited version is rendered once it is approved (background right away; subtitles, hook, and sticker by the next hourly run) (prepare_status pending, running, then ready with variant_url, or failed with prepare_error; three attempts) and posts only when ready.\n\ncheckpoints holds the numbers read at 1, 3, and 7 days (d1, d3, d7). An item wins when its views reach win_target: half the original reel's views, or 10,000, whichever is lower. Winners stay trial reels: share one to your followers from the Instagram app."
      }
    },
    "/trial-reels/programs/{connectionId}": {
      "put": {
        "tags": [
          "trial reels"
        ],
        "summary": "turn the trial reel program for one Instagram account on or off, or change its settings",
        "operationId": "updateTrialReelProgram",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TrialReelProgramUpdate"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "program": {
                      "id": "9d2e7c4a-1b3f-4a5e-8c6d-7e8f9a0b1c2d",
                      "enabled": true,
                      "auto_approve": false,
                      "reels_per_day": 1,
                      "skip_caption_terms": [],
                      "timezone": "America/New_York",
                      "edit_kinds": [
                        "reshare"
                      ],
                      "last_scan_at": "2026-10-29T14:02:11.000Z",
                      "last_run_at": null,
                      "last_note": "scan found 41 reels with views; queued 7 at 1.5x the median of 806 views or more"
                    },
                    "scan": {
                      "queued": 7,
                      "rated": 41,
                      "median_views": 806,
                      "note": "scan found 41 reels with views; queued 7 at 1.5x the median of 806 views or more"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: invalid body, unknown timezone, or the account can't post trial reels",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: missing the send scope (enabled or auto_approve true), or not on pro or premium",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: no active Instagram connection with this id",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "connectionId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "turn the program on or off. Turning it on the first time scans the account's reels (see the scan endpoint) and returns the result as scan. Needs the send scope."
                  },
                  "auto_approve": {
                    "type": "boolean",
                    "description": "post queued reels without approving each one (reels with no caption still wait for one). Turning it on approves what is already waiting. Needs the send scope.",
                    "default": false
                  },
                  "reels_per_day": {
                    "type": "integer",
                    "description": "trial reels a day, 1-3, one per posting hour",
                    "default": 1
                  },
                  "skip_caption_terms": {
                    "type": "array",
                    "description": "up to 20 words or phrases (50 characters each); a reel whose caption contains one is never queued"
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA timezone the posting hours are in, e.g. America/New_York",
                    "default": "UTC"
                  },
                  "edit_kinds": {
                    "type": "array",
                    "description": "kinds new reels take in turn: reshare (the original video), background (on a colored background), subtitles (burned-in, for reels with speech and no captions on screen), hook (a strong later line played first), and sticker (a reply card with a comment Claude writes); a kind that has not shipped yet answers 400",
                    "default": [
                      "reshare"
                    ]
                  }
                }
              }
            }
          }
        },
        "description": "connectionId is the Instagram account's connection_id from GET /trial-reels (or GET /connections).\n\nnothing posts until a queued reel is approved (PATCH /trial-reels/items/{id}, approve-all, or auto_approve). Approved reels post one per posting hour, up to reels_per_day, never within 2 hours of another post on the same account: dropspace's own (scheduled or published) and any other post Instagram lists, such as one made by hand or another app's trial reels.\n\neach trial reel is a launch on your account, so it counts toward your plan's launches and shows on your launches page.\n\nthe reel is posted as Instagram's trial reel (graduation MANUAL): only non-followers see it until you share it to followers in the Instagram app. @mentions are taken out of the reused caption."
      }
    },
    "/trial-reels/programs/{connectionId}/scan": {
      "post": {
        "tags": [
          "trial reels"
        ],
        "summary": "scan the account's reels again and queue the strong ones",
        "operationId": "scanTrialReels",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TrialReelScanResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "queued": 2,
                    "rated": 43,
                    "median_views": 812,
                    "note": "scan found 43 reels with views; queued 2 at 1.5x the median of 812 views or more"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: Instagram refused the read (reconnect the account)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: not on the pro or premium plan",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: no program for this connection (save one with PUT first)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: a scan for this account is already running",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "RATE_001: scanned less than 10 minutes ago",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "connectionId"
          }
        ],
        "description": "reads the account's reels from the last 180 days (up to 100) with their views. A reel is queued when its views are at least 1.5x the median, it is older than 21 days, it has a video file Instagram will hand over, its caption has no skip term, it is on the profile grid (a trial reel, from dropspace or another app, is never reshared), and it was never queued before (removed and failed reels do not come back). Up to 20 wait at once.\n\nneeds at least 5 reels with views older than 21 days; note says why when nothing was queued. One scan per account every 10 minutes.\n\nwith auto_approve on, the new reels are approved (they will post) only when the key has the send scope; with the write scope alone they wait for approval."
      }
    },
    "/trial-reels/programs/{connectionId}/approve-all": {
      "post": {
        "tags": [
          "trial reels"
        ],
        "summary": "approve every waiting reel with a caption on one account's program",
        "operationId": "approveAllTrialReels",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TrialReelApproveAllResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "approved": 6
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: missing the send scope, or not on pro or premium",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: no program for this connection",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "connectionId"
          }
        ],
        "description": "approved reels post at the next posting hours, so this needs the send scope."
      }
    },
    "/trial-reels/items/{id}": {
      "patch": {
        "tags": [
          "trial reels"
        ],
        "summary": "approve or hold a waiting reel, or change its caption",
        "operationId": "updateTrialReelItem",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TrialReelQueueItem"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c",
                    "status": "queued",
                    "kind": "reshare",
                    "prepare_status": "none",
                    "prepare_error": null,
                    "variant_url": null,
                    "edit_summary": null,
                    "approved": true,
                    "reason": "1,933 views, 2.4x your median of 806",
                    "caption": "load the next track early",
                    "source": {
                      "media_id": "18118432868104282",
                      "permalink": "https://www.instagram.com/reel/DfAJhNWDpoh/",
                      "caption": "load the next track early @djnova",
                      "views": 1933,
                      "posted_at": "2026-08-30T18:12:00.000Z"
                    },
                    "win_target": 967,
                    "launch_id": null,
                    "post_id": null,
                    "post_url": null,
                    "claimed_at": null,
                    "posted_at": null,
                    "checkpoints": {},
                    "outcome_at": null,
                    "failure": null,
                    "created_at": "2026-10-29T14:02:11.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: nothing to change, caption too long, or approving with no caption",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: missing the send scope (approved: true), or not on pro or premium",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: trial reel not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: the reel is no longer waiting",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "approved": {
                    "type": "boolean",
                    "description": "true lets it post at the next posting hour (send scope); false holds it"
                  },
                  "caption": {
                    "type": "string",
                    "description": "the caption the trial reel posts with, up to 2,200 characters; an approved reel needs one"
                  },
                  "kind": {
                    "type": "string",
                    "description": "reshare, background, subtitles, hook, or sticker: which version posts. A new kind holds the reel (like a new caption) and starts its edit over; one version per kind per reel."
                  }
                }
              }
            }
          }
        },
        "description": "only waiting (queued) reels change; one that started posting answers 409.\n\na new caption holds the reel (approved becomes false) unless approved: true is sent with it, so what posts is always a caption someone approved."
      },
      "delete": {
        "tags": [
          "trial reels"
        ],
        "summary": "remove a waiting reel from the queue for good",
        "operationId": "removeTrialReelItem",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TrialReelQueueItem"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c",
                    "status": "removed",
                    "kind": "reshare",
                    "prepare_status": "none",
                    "prepare_error": null,
                    "variant_url": null,
                    "edit_summary": null,
                    "approved": false,
                    "reason": "1,933 views, 2.4x your median of 806",
                    "caption": "load the next track early",
                    "source": {
                      "media_id": "18118432868104282",
                      "permalink": "https://www.instagram.com/reel/DfAJhNWDpoh/",
                      "caption": "load the next track early @djnova",
                      "views": 1933,
                      "posted_at": "2026-08-30T18:12:00.000Z"
                    },
                    "win_target": 967,
                    "launch_id": null,
                    "post_id": null,
                    "post_url": null,
                    "claimed_at": null,
                    "posted_at": null,
                    "checkpoints": {},
                    "outcome_at": null,
                    "failure": null,
                    "created_at": "2026-10-29T14:02:11.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: not on the pro or premium plan",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: trial reel not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: the reel is no longer waiting",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "a removed reel is never queued again by a scan."
      }
    },
    "/songs": {
      "get": {
        "tags": [
          "songs"
        ],
        "summary": "your songs, newest first, without waveforms",
        "operationId": "listSongs",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SongSummary"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                      "title": "heart of mine",
                      "source": "upload",
                      "source_url": null,
                      "status": "ready",
                      "error": null,
                      "duration_seconds": 212.4,
                      "size_bytes": 3412011,
                      "audio_url": "https://.../songs/<user>/songs/<id>/audio.m4a",
                      "lyrics_status": "ready",
                      "created_at": "2026-11-01T18:02:11.000Z",
                      "updated_at": "2026-11-01T18:03:40.000Z"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 50,
                    "total": 1,
                    "total_pages": 1
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "songs per page, 1-100",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ]
      },
      "post": {
        "tags": [
          "songs"
        ],
        "summary": "add a song from a link or a public audio file url. the song comes back `pending`; read `GET /songs/:id` until it is `ready` or `failed`",
        "operationId": "createSong",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Song"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "title": "untitled song",
                    "source": "link",
                    "source_url": "https://soundcloud.com/ynho/heart-of-mine",
                    "status": "pending",
                    "error": null,
                    "duration_seconds": null,
                    "size_bytes": null,
                    "audio_url": null,
                    "lyrics_status": "none",
                    "peaks": null,
                    "created_at": "2026-11-01T18:02:11.000Z",
                    "updated_at": "2026-11-01T18:02:11.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: no link_url or audio_url, or a link to another site",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "BILLING_006: songs are part of the pro and premium plans",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: you have 100 songs; delete some to add more",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "link_url": {
                    "type": "string",
                    "description": "a YouTube or SoundCloud link (one of link_url or audio_url). the page's title names the song unless `title` is given. YouTube can refuse downloads from a server; the song then fails with an error that says to upload the file instead"
                  },
                  "audio_url": {
                    "type": "string",
                    "description": "a public https url of an audio file: mp3, m4a, wav, aac, flac, or ogg, up to 50 MB (one of link_url or audio_url)"
                  },
                  "title": {
                    "type": "string",
                    "description": "the title, up to 200 characters"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/songs/{id}": {
      "get": {
        "tags": [
          "songs"
        ],
        "summary": "one song with its waveform: `peaks` is 400 numbers from 0 to 1 across the song once it is ready, for picking a snippet",
        "operationId": "getSong",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Song"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "title": "heart of mine",
                    "source": "upload",
                    "source_url": null,
                    "status": "ready",
                    "error": null,
                    "duration_seconds": 212.4,
                    "size_bytes": 3412011,
                    "audio_url": "https://.../songs/<user>/songs/<id>/audio.m4a",
                    "lyrics_status": "none",
                    "peaks": [
                      0.12,
                      0.3,
                      0.41,
                      "..."
                    ],
                    "created_at": "2026-11-01T18:02:11.000Z",
                    "updated_at": "2026-11-01T18:03:40.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: song not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      },
      "patch": {
        "tags": [
          "songs"
        ],
        "summary": "rename a song",
        "operationId": "updateSong",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Song"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "title": "heart of mine (demo)",
                    "source": "upload",
                    "source_url": null,
                    "status": "ready",
                    "error": null,
                    "duration_seconds": 212.4,
                    "size_bytes": 3412011,
                    "audio_url": "https://.../audio.m4a",
                    "lyrics_status": "none",
                    "peaks": [
                      0.12,
                      0.3,
                      "..."
                    ],
                    "created_at": "2026-11-01T18:02:11.000Z",
                    "updated_at": "2026-11-01T18:10:02.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: title missing or too long",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: song not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "the new title, up to 200 characters"
                  }
                },
                "required": [
                  "title"
                ]
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "songs"
        ],
        "summary": "delete a song and its audio file",
        "operationId": "deleteSong",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SongDeletion"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "deleted": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: song not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/songs/{id}/lyrics": {
      "get": {
        "tags": [
          "songs"
        ],
        "summary": "the song's lyrics with word timings (seconds from the start), transcribed on the first request and kept after. a long song can take up to a minute the first time. a song with no recognizable words comes back with empty `words`",
        "operationId": "getSongLyrics",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SongLyrics"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "song_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "language": "en",
                    "text": "you're moving on. it really could have been us.",
                    "words": [
                      {
                        "text": "you're",
                        "start": 9.52,
                        "end": 10.2
                      },
                      {
                        "text": "moving",
                        "start": 10.2,
                        "end": 10.61
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: song not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: the song is not ready yet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "SERVER_001: the lyrics could not be read; try again",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/songs/{id}/retry": {
      "post": {
        "tags": [
          "songs"
        ],
        "summary": "run a failed (or stuck) import again. three attempts in all",
        "operationId": "retrySongImport",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Song"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "title": "heart of mine",
                    "source": "link",
                    "source_url": "https://soundcloud.com/ynho/heart-of-mine",
                    "status": "pending",
                    "error": null,
                    "duration_seconds": null,
                    "size_bytes": null,
                    "audio_url": null,
                    "lyrics_status": "none",
                    "peaks": null,
                    "created_at": "2026-11-01T18:02:11.000Z",
                    "updated_at": "2026-11-01T18:12:30.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: song not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: the import is still running",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/songs/{id}/reels": {
      "post": {
        "tags": [
          "songs"
        ],
        "summary": "make a 9:16 lyric reel from a snippet of a ready song: the snippet's audio under footage, with the lyric lines inside the snippet burned in and, if given, a hook line held across the whole snippet. the lyrics are read from the song on the first reel. the render runs on the server, so the reel comes back `pending`; read `GET /song-reels/:id` until it is `ready` (video_url, and it is in the media library) or `failed`. with `footage_mode` `ai` the reel first generates its b-roll (`footage_status` `generating`), then renders. counts against the plan's song reels per billing period (pro 30, premium 100): a rendered reel keeps its slot even if it is deleted; a failed render gives it back",
        "operationId": "createSongReel",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SongReel"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "9b1f0c2d-4e5a-4f6b-8c7d-0e1f2a3b4c5d",
                    "song_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "title": "heart of mine 0:42-1:12",
                    "snippet_start": 42,
                    "snippet_end": 72,
                    "style": "karaoke",
                    "footage_mode": "clips",
                    "clip_ids": [
                      "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"
                    ],
                    "background": null,
                    "hook_text": null,
                    "rollout_id": null,
                    "variant_index": null,
                    "variant_note": null,
                    "ai_prompt": null,
                    "footage_status": null,
                    "lines": [
                      {
                        "start": 0.4,
                        "end": 1.9,
                        "text": "you're moving on."
                      }
                    ],
                    "render_status": "pending",
                    "render_error": null,
                    "video_url": null,
                    "thumbnail_url": null,
                    "duration_seconds": null,
                    "media_library_id": null,
                    "launch_id": null,
                    "created_at": "2026-11-02T01:10:00.000Z",
                    "updated_at": "2026-11-02T01:10:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: the snippet doesn't fit, or no clips were picked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "BILLING_006: songs are part of the pro and premium plans, or the plan has no AI videos (footage_mode ai)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: song not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: the song is not ready yet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "MEDIA_001: this billing period's song reels, or its AI videos (footage_mode ai), are used up",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "snippet_start": {
                    "type": "number",
                    "description": "seconds from the start of the song"
                  },
                  "snippet_end": {
                    "type": "number",
                    "description": "5 to 30 seconds after snippet_start"
                  },
                  "style": {
                    "type": "string",
                    "description": "how the lyrics look: `lower-third` (bold lines low on the frame), `center-bold`, `karaoke` (lines light up word by word), `one-word` (one big word at a time), `caps-top` (uppercase across the top)"
                  },
                  "footage_mode": {
                    "type": "string",
                    "description": "`clips` (videos and images from the media library, the clip changing at lyric lines; cuts closer than 1.5 seconds apart are skipped), `none` (the lyrics over a gradient), or `ai` (b-roll generated from `ai_prompt`: `ai_clips` veo clips of 8 seconds, each one of the plan's AI videos, at $1.20 a clip on the AI media meter; the clips join the media library with source `ai`)"
                  },
                  "clip_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "media library ids, in order, up to 20 (footage_mode clips)"
                  },
                  "background": {
                    "type": "string",
                    "description": "`midnight`, `sunset`, `forest`, `sand`, `slate`, or `violet` (footage_mode none); midnight unless given"
                  },
                  "hook_text": {
                    "type": "string",
                    "description": "a line burned in for the whole snippet, up to 90 characters: boxed across the top, or low on the frame under `caps-top`. it also opens the launch caption"
                  },
                  "ai_prompt": {
                    "type": "string",
                    "description": "what the b-roll should show, up to 500 characters (footage_mode ai); the snippet's lyrics stand in when empty. every clip is framed as music-video b-roll with no text or speech"
                  },
                  "ai_clips": {
                    "type": "integer",
                    "description": "how many b-roll clips to generate, 1-4 (footage_mode ai); 2 unless given. two generate at a time",
                    "default": 2
                  }
                },
                "required": [
                  "snippet_start",
                  "snippet_end",
                  "style",
                  "footage_mode"
                ]
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "songs"
        ],
        "summary": "the song's reels, newest first",
        "operationId": "listSongReelsForSong",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SongReel"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "9b1f0c2d-4e5a-4f6b-8c7d-0e1f2a3b4c5d",
                      "song_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                      "title": "heart of mine 0:42-1:12",
                      "snippet_start": 42,
                      "snippet_end": 72,
                      "style": "karaoke",
                      "footage_mode": "clips",
                      "clip_ids": [
                        "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"
                      ],
                      "background": null,
                      "hook_text": null,
                      "rollout_id": null,
                      "variant_index": null,
                      "variant_note": null,
                      "ai_prompt": null,
                      "footage_status": null,
                      "lines": [],
                      "render_status": "ready",
                      "render_error": null,
                      "video_url": "https://.../generated-media/<user>/song-reels/<id>/reel.mp4",
                      "thumbnail_url": "https://.../thumb.jpg",
                      "duration_seconds": 30,
                      "media_library_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
                      "launch_id": null,
                      "created_at": "2026-11-02T01:10:00.000Z",
                      "updated_at": "2026-11-02T01:11:30.000Z"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 50,
                    "total": 1,
                    "total_pages": 1
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: song not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "reels per page, 1-100",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ]
      }
    },
    "/songs/{id}/reels/rollout": {
      "post": {
        "tags": [
          "songs"
        ],
        "summary": "make `count` (2-10) versions of one reel at once, as one rollout: the same snippet, lines, and footage, the style and then the clip order (or the background, with no footage) changing per version, so no two versions are the same reel. every version is a reel of its own (rollout_id, variant_index, variant_note) that counts against the plan's song reels; when fewer slots are left than `count`, nothing is made and the error says how many are left. the versions render in turn on the server. then keep the best with `POST /song-reels/:id/keep`, or launch them all (as trial reels, if you like) with `POST /song-reels/:id/launch`. a rollout with `footage_mode` `ai` generates its b-roll once and shares it",
        "operationId": "createSongReelRollout",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SongReelRollout"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "rollout_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
                    "count": 2,
                    "reels": [
                      {
                        "id": "9b1f0c2d-4e5a-4f6b-8c7d-0e1f2a3b4c5d",
                        "song_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                        "title": "heart of mine 0:42-1:12",
                        "snippet_start": 42,
                        "snippet_end": 72,
                        "style": "karaoke",
                        "footage_mode": "clips",
                        "clip_ids": [
                          "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
                          "1b2c3d4e-5f6a-4b7c-9d0e-1f2a3b4c5d6e"
                        ],
                        "background": null,
                        "hook_text": "wait for the drop",
                        "rollout_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
                        "variant_index": 1,
                        "variant_note": "karaoke · clips 1, 2",
                        "ai_prompt": null,
                        "footage_status": null,
                        "lines": [],
                        "render_status": "pending",
                        "render_error": null,
                        "video_url": null,
                        "thumbnail_url": null,
                        "duration_seconds": null,
                        "media_library_id": null,
                        "launch_id": null,
                        "created_at": "2026-11-02T01:10:00.000Z",
                        "updated_at": "2026-11-02T01:10:00.000Z"
                      },
                      {
                        "id": "8a0e9b1c-3d4e-4f5a-9b6c-7d8e9f0a1b2c",
                        "song_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                        "title": "heart of mine 0:42-1:12",
                        "snippet_start": 42,
                        "snippet_end": 72,
                        "style": "one-word",
                        "footage_mode": "clips",
                        "clip_ids": [
                          "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
                          "1b2c3d4e-5f6a-4b7c-9d0e-1f2a3b4c5d6e"
                        ],
                        "background": null,
                        "hook_text": "wait for the drop",
                        "rollout_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
                        "variant_index": 2,
                        "variant_note": "one word · clips 1, 2",
                        "ai_prompt": null,
                        "footage_status": null,
                        "lines": [],
                        "render_status": "pending",
                        "render_error": null,
                        "video_url": null,
                        "thumbnail_url": null,
                        "duration_seconds": null,
                        "media_library_id": null,
                        "launch_id": null,
                        "created_at": "2026-11-02T01:10:00.000Z",
                        "updated_at": "2026-11-02T01:10:00.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: the snippet doesn't fit, no clips were picked, count is outside 2-10, or fewer distinct versions are possible than count (one style and one clip make one reel; the message says how many)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "BILLING_006: songs are part of the pro and premium plans",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: song not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: the song is not ready yet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "MEDIA_001: fewer song reels are left this billing period than count; the message says how many",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "count": {
                    "type": "integer",
                    "description": "how many versions, 2-10"
                  },
                  "styles": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "the lyric styles the versions cycle through; all five when omitted"
                  },
                  "snippet_start": {
                    "type": "number",
                    "description": "seconds from the start of the song"
                  },
                  "snippet_end": {
                    "type": "number",
                    "description": "5 to 30 seconds after snippet_start"
                  },
                  "style": {
                    "type": "string",
                    "description": "the first version's style; the versions cycle through `styles` from there"
                  },
                  "footage_mode": {
                    "type": "string",
                    "description": "`clips`, `none`, or `ai`, with `clip_ids`, `background`, `hook_text`, `ai_prompt`, and `ai_clips` as for `POST /songs/:id/reels`"
                  }
                },
                "required": [
                  "count",
                  "snippet_start",
                  "snippet_end",
                  "style",
                  "footage_mode"
                ]
              }
            }
          }
        }
      }
    },
    "/song-reels": {
      "get": {
        "tags": [
          "songs"
        ],
        "summary": "every lyric reel, newest first (a rollout's versions in order)",
        "operationId": "listSongReels",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SongReel"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "9b1f0c2d-4e5a-4f6b-8c7d-0e1f2a3b4c5d",
                      "song_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                      "title": "heart of mine 0:42-1:12",
                      "snippet_start": 42,
                      "snippet_end": 72,
                      "style": "lower-third",
                      "footage_mode": "none",
                      "clip_ids": [],
                      "background": "sunset",
                      "hook_text": null,
                      "rollout_id": null,
                      "variant_index": null,
                      "variant_note": null,
                      "ai_prompt": null,
                      "footage_status": null,
                      "lines": [],
                      "render_status": "ready",
                      "render_error": null,
                      "video_url": "https://.../reel.mp4",
                      "thumbnail_url": "https://.../thumb.jpg",
                      "duration_seconds": 30,
                      "media_library_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
                      "launch_id": null,
                      "created_at": "2026-11-02T01:10:00.000Z",
                      "updated_at": "2026-11-02T01:11:30.000Z"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 50,
                    "total": 1,
                    "total_pages": 1
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "song_id",
            "in": "query",
            "required": false,
            "description": "only this song's reels",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "rollout_id",
            "in": "query",
            "required": false,
            "description": "only this rollout's versions",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "reels per page, 1-100",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ]
      }
    },
    "/song-reels/{id}": {
      "get": {
        "tags": [
          "songs"
        ],
        "summary": "one reel, with the lyric lines inside its snippet and their timing (seconds from the snippet's start)",
        "operationId": "getSongReel",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SongReel"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "9b1f0c2d-4e5a-4f6b-8c7d-0e1f2a3b4c5d",
                    "song_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "title": "heart of mine 0:42-1:12",
                    "snippet_start": 42,
                    "snippet_end": 72,
                    "style": "karaoke",
                    "footage_mode": "clips",
                    "clip_ids": [
                      "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"
                    ],
                    "background": null,
                    "hook_text": null,
                    "rollout_id": null,
                    "variant_index": null,
                    "variant_note": null,
                    "ai_prompt": null,
                    "footage_status": null,
                    "lines": [
                      {
                        "start": 0.4,
                        "end": 1.9,
                        "text": "you're moving on."
                      }
                    ],
                    "render_status": "ready",
                    "render_error": null,
                    "video_url": "https://.../reel.mp4",
                    "thumbnail_url": "https://.../thumb.jpg",
                    "duration_seconds": 30,
                    "media_library_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
                    "launch_id": null,
                    "created_at": "2026-11-02T01:10:00.000Z",
                    "updated_at": "2026-11-02T01:11:30.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: reel not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      },
      "delete": {
        "tags": [
          "songs"
        ],
        "summary": "delete a reel. its media library item and any launch made from it stay",
        "operationId": "deleteSongReel",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SongReelDeletion"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "9b1f0c2d-4e5a-4f6b-8c7d-0e1f2a3b4c5d",
                    "deleted": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: reel not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/song-reels/{id}/retry": {
      "post": {
        "tags": [
          "songs"
        ],
        "summary": "render a failed (or stuck) reel again. three attempts in all",
        "operationId": "retrySongReelRender",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SongReel"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "9b1f0c2d-4e5a-4f6b-8c7d-0e1f2a3b4c5d",
                    "song_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "title": "heart of mine 0:42-1:12",
                    "snippet_start": 42,
                    "snippet_end": 72,
                    "style": "karaoke",
                    "footage_mode": "clips",
                    "clip_ids": [
                      "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"
                    ],
                    "background": null,
                    "hook_text": null,
                    "rollout_id": null,
                    "variant_index": null,
                    "variant_note": null,
                    "ai_prompt": null,
                    "footage_status": null,
                    "lines": [],
                    "render_status": "pending",
                    "render_error": null,
                    "video_url": null,
                    "thumbnail_url": null,
                    "duration_seconds": null,
                    "media_library_id": null,
                    "launch_id": null,
                    "created_at": "2026-11-02T01:10:00.000Z",
                    "updated_at": "2026-11-02T01:20:00.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: reel not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: the render is still running",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/song-reels/{id}/launch": {
      "post": {
        "tags": [
          "songs"
        ],
        "summary": "a draft launch carrying the reel as its video (attached to instagram) and the hook line and the snippet's lyrics as the instagram caption; finish it with PATCH /launches/:id (platforms, caption, schedule) and publish it as usual. with `trial_reel` true the draft is an Instagram trial reel (shown to non-followers first; the account must be a professional account with 200 or more followers, refused with the reason otherwise). the draft is one of the plan's launches for the period, like any launch you create. a reel keeps one launch: a second call returns the same launch_id",
        "operationId": "launchSongReel",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SongReel"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "9b1f0c2d-4e5a-4f6b-8c7d-0e1f2a3b4c5d",
                    "song_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "title": "heart of mine 0:42-1:12",
                    "snippet_start": 42,
                    "snippet_end": 72,
                    "style": "karaoke",
                    "footage_mode": "clips",
                    "clip_ids": [
                      "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"
                    ],
                    "background": null,
                    "hook_text": null,
                    "rollout_id": null,
                    "variant_index": null,
                    "variant_note": null,
                    "ai_prompt": null,
                    "footage_status": null,
                    "lines": [],
                    "render_status": "ready",
                    "render_error": null,
                    "video_url": "https://.../reel.mp4",
                    "thumbnail_url": "https://.../thumb.jpg",
                    "duration_seconds": 30,
                    "media_library_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
                    "launch_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
                    "created_at": "2026-11-02T01:10:00.000Z",
                    "updated_at": "2026-11-02T01:25:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: the Instagram account cannot post a trial reel (the message says why)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: reel not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: the reel is not ready yet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "trial_reel": {
                    "type": "boolean",
                    "description": "post it as an Instagram trial reel (instagram_settings post_type trial_reel, graduation MANUAL)"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/song-reels/{id}/keep": {
      "post": {
        "tags": [
          "songs"
        ],
        "summary": "keep this version of a rollout: the rollout's other versions are deleted along with their media library items and files. a version that already has a launch stays (the launch needs its video). returns the kept reel",
        "operationId": "keepSongReel",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SongReel"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "9b1f0c2d-4e5a-4f6b-8c7d-0e1f2a3b4c5d",
                    "song_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f",
                    "title": "heart of mine 0:42-1:12",
                    "snippet_start": 42,
                    "snippet_end": 72,
                    "style": "karaoke",
                    "footage_mode": "clips",
                    "clip_ids": [
                      "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"
                    ],
                    "background": null,
                    "hook_text": "wait for the drop",
                    "rollout_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
                    "variant_index": 1,
                    "variant_note": "karaoke",
                    "ai_prompt": null,
                    "footage_status": null,
                    "lines": [],
                    "render_status": "ready",
                    "render_error": null,
                    "video_url": "https://.../reel.mp4",
                    "thumbnail_url": "https://.../thumb.jpg",
                    "duration_seconds": 30,
                    "media_library_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
                    "launch_id": null,
                    "created_at": "2026-11-02T01:10:00.000Z",
                    "updated_at": "2026-11-02T01:30:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: this reel is not one of a rollout's versions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: reel not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/reports": {
      "get": {
        "tags": [
          "reports"
        ],
        "summary": "your saved reports, newest first, without their bodies",
        "operationId": "listReports",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ReportSummary"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "4c1e8f2a-7b3d-4e5f-9a0b-1c2d3e4f5a6b",
                      "title": "Instagram audit - 10/29/2026",
                      "kind": "audit",
                      "source": "mcp",
                      "created_at": "2026-10-29T18:02:11.000Z"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 50,
                    "total": 1,
                    "total_pages": 1
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "reports per page, 1-100",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ]
      },
      "post": {
        "tags": [
          "reports"
        ],
        "summary": "save a markdown report",
        "operationId": "createReport",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Report"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: invalid json, missing title or body, or too long",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: missing the write scope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: 200 reports saved already",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "1-200 characters"
                  },
                  "body": {
                    "type": "string",
                    "description": "the report in markdown, up to 100,000 characters"
                  },
                  "kind": {
                    "type": "string",
                    "description": "audit, best_times, winners, or other",
                    "default": "other"
                  },
                  "source": {
                    "type": "string",
                    "description": "mcp (saved by an AI app through the MCP server) or api",
                    "default": "api"
                  }
                },
                "required": [
                  "title",
                  "body"
                ]
              }
            }
          }
        },
        "description": "at most 200 saved reports per user; a save past that answers 409 and nothing is deleted for you. delete old ones with DELETE /reports/{id}.\n\nthe body is stored as written. the reports page renders headings, lists, bold, and links; raw HTML is shown as text."
      }
    },
    "/reports/{id}": {
      "get": {
        "tags": [
          "reports"
        ],
        "summary": "one saved report with its markdown body",
        "operationId": "getReport",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Report"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: report not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      },
      "delete": {
        "tags": [
          "reports"
        ],
        "summary": "delete a saved report",
        "operationId": "deleteReport",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/ReportDeletion"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "4c1e8f2a-7b3d-4e5f-9a0b-1c2d3e4f5a6b",
                    "deleted": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: missing the write scope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: report not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/reddit/subreddits/suggest": {
      "post": {
        "tags": [
          "reddit"
        ],
        "summary": "ICP-matched subreddit discovery. pass a product brief; get back verified, real subreddits with a promo-policy classification and a green/yellow/red standing badge for THIS account. `standing.level` answers 'can this account post here without getting filtered': green means it has participated here; yellow means build standing first; red means a hard blocker (banned promo, private sub, or a weak account). `standing.promo_share` is the account's promotional share of its footprint in the community (null when there's no footprint yet). prefer green subs, and earn standing in yellow ones by commenting before you post. the launch fan-out enforces reddit's 90:10 promo norm at publish time, so posting where you have no standing is skipped, not sent.",
        "operationId": "suggestSubreddits",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SubredditSuggestions"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "icp_summary": "indie developers shipping side projects",
                    "suggestions": [
                      {
                        "name": "SideProject",
                        "title": "Side Project",
                        "subscribers": 180000,
                        "over18": false,
                        "subreddit_type": "public",
                        "promo_policy": "allowed",
                        "promo_evidence": "self-promotion saturday thread",
                        "standing": {
                          "level": "green",
                          "tier": "active",
                          "promo_posts_here": 1,
                          "contributions_here": 14,
                          "promo_share": 0.06,
                          "reasons": [
                            "you're active here (14 comments)"
                          ]
                        },
                        "reason": "indie devs share and get feedback on side projects here"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "PLATFORM_001: api key's account has no reddit connection; SERVER_002: brief missing or out of range",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "brief": {
                    "type": "string",
                    "description": "what your product is and who it's for"
                  }
                },
                "required": [
                  "brief"
                ]
              }
            }
          }
        },
        "description": "api-key auth only: needs the caller's reddit oauth token to verify subs + compute standing. wallet/mpp agents get an empty result.\n\nnothing here posts; it only reads. rate-limited per account (the discovery sweep is expensive on reddit's shared 60/min quota)."
      }
    },
    "/media-library": {
      "get": {
        "tags": [
          "media library"
        ],
        "summary": "list media library items, newest first",
        "operationId": "listMediaLibrary",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MediaLibraryItem"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "uuid",
                      "url": "https://...",
                      "type": "image",
                      "mime_type": "image/jpeg",
                      "width": 1080,
                      "height": 1350,
                      "size_bytes": 482113,
                      "thumbnail_url": null,
                      "filename": "desk.jpg",
                      "description": "the product on a wooden desk next to a laptop",
                      "source": "upload",
                      "use_count": 2,
                      "last_used_at": "ISO 8601 | null",
                      "created_at": "ISO 8601",
                      "updated_at": "ISO 8601"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 50,
                    "total": 1,
                    "total_pages": 1
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "items per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ]
      },
      "post": {
        "tags": [
          "media library"
        ],
        "summary": "add photos or videos by public URL (1-20 per call; a URL already in the library is skipped; 500 items max). images without a description are captioned on autopilot's next run; give videos a description or a thumbnail_url",
        "operationId": "addMediaLibraryItems",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/MediaLibraryAddResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "added": [
                      {
                        "id": "uuid",
                        "url": "https://...",
                        "type": "image",
                        "mime_type": "image/jpeg",
                        "width": 1080,
                        "height": 1350,
                        "size_bytes": 482113,
                        "thumbnail_url": null,
                        "filename": "desk.jpg",
                        "description": "the product on a wooden desk next to a laptop",
                        "source": "upload",
                        "use_count": 2,
                        "last_used_at": "ISO 8601 | null",
                        "created_at": "ISO 8601",
                        "updated_at": "ISO 8601"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "each: url (public http(s)), type (image | video), and optional description (max 500), thumbnail_url, mime_type, width, height, size_bytes, filename"
                  }
                },
                "required": [
                  "items"
                ]
              }
            }
          }
        }
      }
    },
    "/media-library/{id}": {
      "patch": {
        "tags": [
          "media library"
        ],
        "summary": "set an item's description (what it shows); null clears it",
        "operationId": "updateMediaLibraryItem",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/MediaLibraryItem"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "url": "https://...",
                    "type": "image",
                    "mime_type": "image/jpeg",
                    "width": 1080,
                    "height": 1350,
                    "size_bytes": 482113,
                    "thumbnail_url": null,
                    "filename": "desk.jpg",
                    "description": "the product on a wooden desk next to a laptop",
                    "source": "upload",
                    "use_count": 2,
                    "last_used_at": "ISO 8601 | null",
                    "created_at": "ISO 8601",
                    "updated_at": "ISO 8601"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "what the media shows"
                  }
                },
                "required": [
                  "description"
                ]
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "media library"
        ],
        "summary": "remove an item from the library; launches that already posted it keep their media",
        "operationId": "deleteMediaLibraryItem",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/MediaLibraryDeleteResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "deleted": true
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/scene-clips": {
      "post": {
        "tags": [
          "media library"
        ],
        "summary": "cut a long video into 2 to 8 second clips at its scene changes, up to 40 a job, each with a thumbnail, for the media library (footage for lyric reels and autopilot). the job comes back `pending`; read `GET /scene-clips/:id` until it is `ready` or `failed`. pro and premium; at most 10 jobs a day and one running at a time",
        "operationId": "createSceneClipJob",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SceneClipJob"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "3f6a4c8d-9e0f-4a2b-8c3d-4e5f6a7b8c9d",
                    "source": "link",
                    "source_url": "https://www.youtube.com/watch?v=abc123",
                    "source_title": null,
                    "source_media_id": null,
                    "source_duration_seconds": null,
                    "status": "pending",
                    "error": null,
                    "attempts": 1,
                    "clips_made": 0,
                    "clips_added": 0,
                    "clips": [],
                    "note": null,
                    "created_at": "2026-11-02T18:02:11.000Z",
                    "updated_at": "2026-11-02T18:02:11.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: no source, more than one, a link to another site, or a library item that isn't a video",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "BILLING_006: cutting clips is part of the pro and premium plans",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: media item not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: one video is being cut already; wait for it to finish",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "MEDIA_001: 10 jobs started in the last day",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "media_library_id": {
                    "type": "string",
                    "description": "a video in the media library (one of media_library_id, link_url, or video_url)"
                  },
                  "link_url": {
                    "type": "string",
                    "description": "a YouTube link, up to 15 minutes, fetched at up to 720p (one of the three). the page's title names the clips. YouTube can refuse downloads from a server; the job then fails with an error that says to upload the video instead"
                  },
                  "video_url": {
                    "type": "string",
                    "description": "a public https url of an mp4 or mov up to 512 MB (one of the three). only the first 15 minutes are scanned"
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "media library"
        ],
        "summary": "list clip jobs, newest first. reading a ready job adds its clips to the media library",
        "operationId": "listSceneClipJobs",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SceneClipJob"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "3f6a4c8d-9e0f-4a2b-8c3d-4e5f6a7b8c9d",
                      "source": "library",
                      "source_url": "https://.../library/abc/summer-tour.mp4",
                      "source_title": "summer tour",
                      "source_media_id": "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
                      "source_duration_seconds": 184.2,
                      "status": "ready",
                      "error": null,
                      "attempts": 1,
                      "clips_made": 23,
                      "clips_added": 23,
                      "clips": [
                        {
                          "start": 0,
                          "end": 4.2,
                          "video_url": "https://.../scene-clips/3f6a.../clip-01.mp4",
                          "thumbnail_url": "https://.../scene-clips/3f6a.../clip-01.jpg",
                          "media_library_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f"
                        }
                      ],
                      "note": null,
                      "created_at": "2026-11-02T18:02:11.000Z",
                      "updated_at": "2026-11-02T18:06:40.000Z"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 50,
                    "total": 1,
                    "total_pages": 1
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "jobs per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ]
      }
    },
    "/scene-clips/{id}": {
      "get": {
        "tags": [
          "media library"
        ],
        "summary": "one clip job. `status` runs pending, running, ready, or failed (`error` says why; a job whose row has not moved for 30 minutes reads as failed, and the backend touches the row while it works, so a long run never does). once ready, `clips` carries each clip's video_url, thumbnail_url, and media_library_id; `note` says when some clips are waiting for room in the library (500 items) and land on a later read",
        "operationId": "getSceneClipJob",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SceneClipJob"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "3f6a4c8d-9e0f-4a2b-8c3d-4e5f6a7b8c9d",
                    "source": "link",
                    "source_url": "https://www.youtube.com/watch?v=abc123",
                    "source_title": "summer tour recap",
                    "source_media_id": null,
                    "source_duration_seconds": 612.5,
                    "status": "ready",
                    "error": null,
                    "attempts": 1,
                    "clips_made": 40,
                    "clips_added": 12,
                    "clips": [
                      {
                        "start": 0,
                        "end": 6.1,
                        "video_url": "https://.../clip-01.mp4",
                        "thumbnail_url": "https://.../clip-01.jpg",
                        "media_library_id": "7d2c1b4e-3f6a-4c8d-9e0f-1a2b3c4d5e6f"
                      }
                    ],
                    "note": "28 clips are waiting for room in your media library (500 items); delete some and open this again",
                    "created_at": "2026-11-02T18:02:11.000Z",
                    "updated_at": "2026-11-02T18:09:02.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: clip job not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      },
      "delete": {
        "tags": [
          "media library"
        ],
        "summary": "delete a clip job. clips already in the media library stay; files nothing points at are removed",
        "operationId": "deleteSceneClipJob",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SceneClipJobDeletion"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "3f6a4c8d-9e0f-4a2b-8c3d-4e5f6a7b8c9d",
                    "deleted": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: clip job not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/scene-clips/{id}/retry": {
      "post": {
        "tags": [
          "media library"
        ],
        "summary": "cut a failed (or stuck) job again, under the same caps as a new job (one at a time, 10 a day). three attempts in all: `attempts` counts them",
        "operationId": "retrySceneClipJob",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SceneClipJob"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "3f6a4c8d-9e0f-4a2b-8c3d-4e5f6a7b8c9d",
                    "source": "url",
                    "source_url": "https://cdn.example.com/tour.mp4",
                    "source_title": "tour",
                    "source_media_id": null,
                    "source_duration_seconds": null,
                    "status": "pending",
                    "error": null,
                    "attempts": 2,
                    "clips_made": 0,
                    "clips_added": 0,
                    "clips": [],
                    "note": null,
                    "created_at": "2026-11-02T18:02:11.000Z",
                    "updated_at": "2026-11-02T18:40:00.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "AUTH_001: missing or invalid api key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: clip job not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: the job is still running, another job is running, or it has failed three times",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "MEDIA_001: 10 jobs started in the last day",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/personas": {
      "get": {
        "tags": [
          "personas"
        ],
        "summary": "list personas with pagination",
        "operationId": "listPersonas",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Persona"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "uuid",
                      "name": "string",
                      "persona_analysis": "object | null",
                      "build_status": "idle|building|complete|error",
                      "build_progress": 0,
                      "build_started_at": "ISO 8601 | null",
                      "build_error": "string | null",
                      "last_analyzed_at": "ISO 8601 | null",
                      "created_at": "ISO 8601",
                      "updated_at": "ISO 8601"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 50,
                    "total": 3,
                    "total_pages": 1
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "items per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ]
      },
      "post": {
        "tags": [
          "personas"
        ],
        "summary": "create a new persona",
        "operationId": "createPersona",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Persona"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: duplicate persona name",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "PERSONA_001: persona creation limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "persona name"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        }
      }
    },
    "/personas/{id}": {
      "get": {
        "tags": [
          "personas"
        ],
        "summary": "get persona with all writing samples",
        "operationId": "getPersona",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Persona"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "PERSONA_002: persona not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "includes persona_analysis, persona_analysis_structured, custom_samples, twitter_samples, reddit_samples, facebook_samples, instagram_samples, tiktok_samples, linkedin_samples, brand_kit (omitted when unset)"
      },
      "patch": {
        "tags": [
          "personas"
        ],
        "summary": "update name and/or writing samples",
        "operationId": "updatePersona",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Persona"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "PERSONA_002: persona not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: duplicate persona name",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "persona name"
                  },
                  "custom_samples": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 50,
                    "description": "plain-text writing samples"
                  },
                  "twitter_samples": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "maxItems": 50,
                    "description": "Twitter writing samples. each item carries its prose in `text`; a plain string is accepted and read as the prose itself"
                  },
                  "reddit_samples": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "maxItems": 50,
                    "description": "Reddit writing samples. each item carries its prose in `body`; a plain string is accepted and read as the prose itself"
                  },
                  "facebook_samples": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "maxItems": 50,
                    "description": "Facebook writing samples. each item carries its prose in `message`; a plain string is accepted and read as the prose itself"
                  },
                  "instagram_samples": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "maxItems": 50,
                    "description": "Instagram writing samples. each item carries its prose in `caption`; a plain string is accepted and read as the prose itself"
                  },
                  "tiktok_samples": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "maxItems": 50,
                    "description": "TikTok writing samples. each item carries its prose in `description`; a plain string is accepted and read as the prose itself"
                  },
                  "linkedin_samples": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "maxItems": 50,
                    "description": "LinkedIn writing samples. each item carries its prose in `commentary`; a plain string is accepted and read as the prose itself"
                  },
                  "brand_kit": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "how autopilot image slides look when autopilot posts as this persona: text_color and outline_color (#RRGGBB), logo_url (public http(s) image), logo_position (top-left | top-right | bottom-left | bottom-right, default top-right). omitted fields keep white text on a black outline; null clears the kit"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "personas"
        ],
        "summary": "delete a persona",
        "operationId": "deletePersona",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "204": {
            "description": "no content"
          },
          "404": {
            "description": "PERSONA_002: persona not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "SERVER_005: persona in use by launches",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "cannot delete if used by any launches"
      }
    },
    "/personas/{id}/analyze": {
      "post": {
        "tags": [
          "personas"
        ],
        "summary": "trigger AI persona analysis (async)",
        "operationId": "analyzePersona",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "202": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/AnalyzeStartedResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "started": true,
                    "persona_id": "uuid"
                  }
                }
              }
            }
          },
          "404": {
            "description": "PERSONA_002: persona not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: already building",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "PERSONA_003: persona build limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "which platforms to analyze. omit to analyze every platform this persona has samples for; pass [] for none"
                  },
                  "include_custom_samples": {
                    "type": "boolean",
                    "description": "include custom_samples in the analysis",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "description": "listen for persona.analyzed webhook when complete"
      }
    },
    "/personas/{id}/finalize": {
      "post": {
        "tags": [
          "personas"
        ],
        "summary": "commit the pending analysis (after analyze) - content generation reads the committed analysis",
        "operationId": "finalizePersona",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/FinalizePersonaResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "success": true,
                    "analysis_limit": {
                      "used": 1,
                      "limit": 3,
                      "remaining": 2
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "PERSONA_004: persona is not ready for review",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "PERSONA_002: persona not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "persona_analysis": {
                    "type": "string",
                    "description": "optionally edited analysis text (defaults to the pending analysis)"
                  },
                  "persona_analysis_structured": {
                    "type": "object",
                    "description": "optionally edited structured analysis"
                  }
                }
              }
            }
          }
        },
        "description": "free - usage was charged at analyze. call once build_status is ready_for_review"
      }
    },
    "/personas/{id}/discard": {
      "post": {
        "tags": [
          "personas"
        ],
        "summary": "discard the pending analysis (preserves any previously committed analysis)",
        "operationId": "discardPersonaAnalysis",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/DiscardPersonaResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "PERSONA_004: persona is not ready for review",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "PERSONA_002: persona not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "free - analyze usage is not refunded"
      }
    },
    "/autopilot": {
      "get": {
        "tags": [
          "autopilot"
        ],
        "summary": "get autopilot status and config",
        "operationId": "getAutopilot",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/AutopilotStatus"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          }
        },
        "description": "config is null until the first PATCH /autopilot call"
      },
      "patch": {
        "tags": [
          "autopilot"
        ],
        "summary": "create or update the autopilot config (merge: only the fields you send change)",
        "operationId": "updateAutopilot",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/AutopilotConfig"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: invalid timezone or no usable connected account for a platform",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "BILLING_006: plan does not include autopilot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "turn nightly runs on/off"
                  },
                  "mode": {
                    "type": "string",
                    "description": "\"review\" (drafts wait for approval) or \"auto\" (publishes on schedule). YouTube posts always hold for review regardless of mode - approve them via the review endpoints",
                    "default": "review"
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "platforms to post on - each needs a connected account. valid: facebook, linkedin, twitter, reddit, instagram, tiktok, youtube"
                  },
                  "formats": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "\"text\", \"visual\" (AI image slides), and/or \"video\"",
                    "default": [
                      "text"
                    ]
                  },
                  "persona_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid",
                    "description": "voice persona for drafts"
                  },
                  "posting_times": {
                    "type": "object",
                    "description": "{ \"times\": [\"HH:MM\"], \"days\": [0-6] } in the config timezone (0 = sunday)"
                  },
                  "run_hour": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 23,
                    "description": "local hour the nightly run fires",
                    "default": 2
                  },
                  "timezone": {
                    "type": "string",
                    "description": "timezone for posting times and runs",
                    "default": "America/New_York"
                  },
                  "product_url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "product link included in posts"
                  },
                  "product_image_url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "reference image for slideshow (visual) posts - each slide is generated from it so it shows the real product. omitted: filled from product_url's page when product_url changes. empty or null: no reference"
                  },
                  "product_brief": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "what you're building, who it's for"
                  },
                  "content_pillars": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 10,
                    "description": "themes the engine rotates across"
                  },
                  "directives": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string",
                      "maxLength": 200
                    },
                    "maxItems": 10,
                    "description": "standing per-post rules the planner honors in every draft (e.g. \"no emojis\", \"always end with a question\") - null clears them"
                  },
                  "min_queue": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 30,
                    "description": "ideas to keep queued",
                    "default": 7
                  },
                  "max_posts_per_day": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "description": "daily posting cap",
                    "default": 4
                  },
                  "track_links": {
                    "type": "boolean",
                    "description": "wrap the post's outbound product link in a dropspace-owned tracked redirect, so click-throughs count toward what autopilot learns from",
                    "default": false
                  },
                  "reuse_media": {
                    "type": "boolean",
                    "description": "reuse the day's first finished AI slideshow or video across your other platforms' posts that day - identical media, per-platform captions; claims spend no generation quota",
                    "default": false
                  },
                  "media_source": {
                    "type": "string",
                    "enum": [
                      "ai",
                      "library",
                      "mixed"
                    ],
                    "description": "where image and video posts get media: ai (generated slides and video), library (only the media library), mixed (library first, AI when nothing fits). an empty library falls back to AI",
                    "default": "ai"
                  },
                  "platform_settings": {
                    "type": "object",
                    "description": "per-platform posting settings stamped into every autopilot launch. tiktok: privacy_level (defaults to SELF_ONLY - posts publish visible only to the account until widened), allow_comments/allow_duet/allow_stitch, commercial disclosure (is_commercial + is_your_brand/is_branded_content). youtube: privacy_status (defaults to private), made_for_kids; AI-content disclosure is always on for autopilot videos",
                    "default": {}
                  }
                }
              }
            }
          }
        },
        "description": "posts created by autopilot consume your monthly launch limit\n\nvisual and video formats also consume your monthly AI media limits"
      }
    },
    "/autopilot/review": {
      "get": {
        "tags": [
          "autopilot"
        ],
        "summary": "list drafts awaiting approval (review mode)",
        "operationId": "listAutopilotReview",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AutopilotReviewItem"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "launch_id": "uuid",
                      "hook": "string",
                      "platform": "twitter",
                      "format": "text",
                      "content": "string | null",
                      "reddit_title": "string | null",
                      "scheduled_date": "ISO 8601 | null",
                      "media_count": 0,
                      "created_at": "ISO 8601"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 20,
                    "total": 3,
                    "total_pages": 1
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "items per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "description": "each item is a draft launch - edit it first with PATCH /launches/:id if needed"
      }
    },
    "/autopilot/review/{launchId}/approve": {
      "post": {
        "tags": [
          "autopilot"
        ],
        "summary": "approve a draft - schedules it for publishing",
        "operationId": "approveAutopilotDraft",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/AutopilotApproveResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "launch_id": "uuid",
                    "status": "scheduled",
                    "scheduled_date": "ISO 8601"
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: draft not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "launchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "launchId"
          }
        ],
        "description": "a stale scheduled_date rolls forward to the next posting slot automatically"
      }
    },
    "/autopilot/review/{launchId}/reject": {
      "post": {
        "tags": [
          "autopilot"
        ],
        "summary": "reject a draft - deletes it and refunds the launch slot",
        "operationId": "rejectAutopilotDraft",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/AutopilotRejectResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "launch_id": "uuid",
                    "rejected": true
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: draft not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "launchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "launchId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "feedback": {
                    "type": "string",
                    "description": "what to avoid next time - feeds future generation"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/autopilot/run": {
      "post": {
        "tags": [
          "autopilot"
        ],
        "summary": "trigger a manual run now (instead of waiting for the nightly run)",
        "operationId": "triggerAutopilotRun",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "202": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/AutopilotRunQueued"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "queued": true,
                    "run_date": "2026-06-12"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: autopilot is not enabled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "BILLING_006: plan does not include autopilot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: autopilot is not set up yet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "RATE_001: manual runs are limited to 2 per hour",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "description": "the insight and idea steps that already completed today are skipped; the scheduling step runs again, filling only slots that have no post yet, so a manual run after a fix (media added, a platform unticked) tops up the same day rather than double-posting"
      }
    },
    "/autopilot/runs": {
      "get": {
        "tags": [
          "autopilot"
        ],
        "summary": "recent run history (one row per run step)",
        "operationId": "listAutopilotRuns",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AutopilotRun"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "run_date": "2026-06-12",
                      "step": "schedule_slots",
                      "status": "completed",
                      "stats": {
                        "created": 3,
                        "slots": 4
                      },
                      "error": null,
                      "started_at": "ISO 8601",
                      "completed_at": "ISO 8601"
                    }
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "rows to return",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 30,
              "default": 9
            }
          }
        ]
      }
    },
    "/recommendations": {
      "get": {
        "tags": [
          "recommendations"
        ],
        "summary": "list recommendations",
        "operationId": "listRecommendations",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Recommendation"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "uuid",
                      "rec_type": "repost_winner",
                      "status": "pending",
                      "platform": "twitter",
                      "launch_id": "uuid",
                      "posting_log_id": "uuid",
                      "payload": {
                        "launch_name": "july feature drop",
                        "post_url": "https://x.com/...",
                        "score": 42.5,
                        "baseline": 6
                      },
                      "score": 42.5,
                      "baseline": 6,
                      "expires_at": "ISO 8601",
                      "applied_launch_id": null,
                      "applied_at": null,
                      "dismissed_at": null,
                      "created_at": "ISO 8601",
                      "updated_at": "ISO 8601"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 20,
                    "total": 3,
                    "total_pages": 1
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "results per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "filter by status",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "applied",
                "dismissed",
                "expired"
              ]
            }
          },
          {
            "name": "launch_id",
            "in": "query",
            "required": false,
            "description": "only recommendations for this launch",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "description": "rec_type is one of: repost_winner, cross_post, boost_winner, promote_winner, pause_underperformer\n\nrecommendations expire automatically (default 14 days), act on them while the post is still riding"
      }
    },
    "/recommendations/{id}/apply": {
      "post": {
        "tags": [
          "recommendations"
        ],
        "summary": "apply a recommendation (executes its one-click action)",
        "operationId": "createApply",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/RecommendationApplyResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "recommendation": {
                      "id": "uuid",
                      "rec_type": "repost_winner",
                      "status": "applied",
                      "...": "..."
                    },
                    "outcome": {
                      "kind": "launch_draft",
                      "launch_id": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: missing ad_account_id for a boost recommendation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: recommendation not found or not owned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: already applied/dismissed, expired, or autopilot not enabled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ad_account_id": {
                    "type": "string",
                    "description": "meta ad account id: required for boost_winner recommendations, ignored otherwise"
                  }
                }
              }
            }
          }
        },
        "description": "repost_winner and cross_post create a DRAFT launch seeded with the winning content. nothing publishes until you schedule it\n\nboost_winner creates a PAUSED boost with the suggested budget. activate it separately to start spend\n\npromote_winner queues the winner into your autopilot queue (autopilot must be enabled)\n\npause_underperformer adds a standing directive to your autopilot config"
      }
    },
    "/recommendations/{id}/dismiss": {
      "post": {
        "tags": [
          "recommendations"
        ],
        "summary": "dismiss a recommendation",
        "operationId": "createDismis",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Recommendation"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "uuid",
                    "rec_type": "repost_winner",
                    "status": "dismissed",
                    "...": "..."
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: recommendation not found or not owned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: recommendation is already applied or dismissed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/media/generate": {
      "post": {
        "tags": [
          "media"
        ],
        "summary": "submit an image or video generation job",
        "operationId": "generateMedia",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "202": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/MediaGenerateResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "status": "processing",
                    "job_id": "uuid",
                    "fal_request_id": "string",
                    "generation_type": "image",
                    "usage": {
                      "used": 3,
                      "limit": 50,
                      "remaining": 47
                    },
                    "plan": "pro"
                  }
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: plan doesn't include media generation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "LAUNCH_001: launch not found or not owned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "MEDIA_001: monthly media generation limit reached; RATE_001: concurrency limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "image",
                      "video",
                      "script_video"
                    ],
                    "description": "generation type"
                  },
                  "launch_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "associated launch"
                  },
                  "platform": {
                    "type": "string",
                    "description": "target platform for the asset - always required, any supported platform. script_video only accepts \"instagram\" or \"tiktok\""
                  },
                  "prompt": {
                    "type": "string",
                    "description": "generation prompt - either prompt or product_description is required; script_video requires an explicit prompt. the effective prompt (yours, or the one derived from product_description) must be 10-2000 chars or the request fails with a 400"
                  },
                  "product_description": {
                    "type": "string",
                    "description": "product context - used to derive a prompt when prompt is omitted"
                  },
                  "options.aspect_ratio": {
                    "type": "string",
                    "enum": [
                      "1:1",
                      "16:9",
                      "9:16",
                      "4:3",
                      "3:4",
                      "3:2",
                      "2:3",
                      "5:4",
                      "4:5",
                      "21:9"
                    ],
                    "description": "aspect ratio (image supports all 10; video/script_video only supports 16:9 and 9:16)"
                  },
                  "options.duration_seconds": {
                    "type": "integer",
                    "enum": [
                      4,
                      6,
                      8
                    ],
                    "description": "video duration",
                    "default": 8
                  },
                  "options.seed": {
                    "type": "number",
                    "description": "generation seed for reproducible output - forwarded to the model for text-to-image and video jobs; ignored when reference_image_url is set (the edit model does not support seeds)"
                  },
                  "options.negative_prompt": {
                    "type": "string",
                    "description": "things to steer the model away from - video generation only (the image model does not support negative prompts; ignored for image jobs)"
                  },
                  "reference_image_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL of a reference image for style/composition guidance (image type only, uses edit endpoint)"
                  },
                  "use_product_image": {
                    "type": "boolean",
                    "description": "use the first image from the launch's product page (scraped from product_url) as the reference image - image type only, ignored when reference_image_url is set, 400 when the launch has no product image"
                  }
                },
                "required": [
                  "type",
                  "launch_id",
                  "platform"
                ]
              }
            }
          }
        },
        "description": "type 'script_video' generates a video from a text script (requires platform 'instagram' or 'tiktok' and an explicit prompt). type 'video' generates from a visual/cinematic prompt"
      }
    },
    "/media/{jobId}": {
      "get": {
        "tags": [
          "media"
        ],
        "summary": "poll media generation status",
        "operationId": "getMedia",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/MediaGenerationJob"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "generation_type": "image",
                    "prompt": "...",
                    "result_url": "https://cdn.dropspace.dev/...",
                    "reference_image_url": "https://cdn.dropspace.dev/... | null",
                    "status": "processing|completed|failed",
                    "progress": 75,
                    "model_id": "string",
                    "error_message": "string | null",
                    "launch_id": "uuid",
                    "created_at": "ISO 8601",
                    "completed_at": "ISO 8601 | null"
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: media job not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "jobId"
          }
        ],
        "description": "listen for media.ready webhook when status becomes completed"
      }
    },
    "/profile": {
      "get": {
        "tags": [
          "account"
        ],
        "summary": "the authenticated user's profile",
        "operationId": "listProfile",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Profile"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "email": "you@example.com",
                    "full_name": "string | null",
                    "avatar_url": "string | null",
                    "role": "user",
                    "has_completed_onboarding": true,
                    "created_at": "ISO 8601",
                    "updated_at": "ISO 8601"
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_004: profile not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "account"
        ],
        "summary": "update your display name",
        "operationId": "updateProfile",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Profile"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "full_name": "string | null",
                    "avatar_url": "string | null"
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "full_name": {
                    "type": "string",
                    "description": "display name"
                  }
                },
                "required": [
                  "full_name"
                ]
              }
            }
          }
        }
      }
    },
    "/billing/portal": {
      "post": {
        "tags": [
          "account"
        ],
        "summary": "a Stripe billing-portal session for managing your subscription. falls back to the web billing page when no Stripe customer exists yet.",
        "operationId": "createPortal",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/BillingPortalResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "url": "https://billing.stripe.com/session/..."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/connections/{platform}/connect": {
      "post": {
        "tags": [
          "connections"
        ],
        "summary": "start an OAuth connect for a platform. returns the URL to send the user to, plus the `state` that identifies the flow on return.",
        "operationId": "createConnect",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/ConnectStartResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "auth_url": "https://...",
                    "state": "string"
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_003: invalid platform",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "platform",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "platform"
          },
          {
            "name": "platform",
            "in": "query",
            "required": true,
            "description": "platform to connect (path parameter)",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/connections": {
      "get": {
        "tags": [
          "connections"
        ],
        "summary": "list your OAuth platform connections",
        "operationId": "listConnections",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Connection"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "uuid",
                      "platform": "twitter",
                      "entity_id": "string",
                      "account_info": {
                        "username": "...",
                        "display_name": "..."
                      },
                      "account_type": "personal",
                      "is_active": true,
                      "inactive_reason": "string | null",
                      "expires_at": "ISO 8601 | null",
                      "created_at": "ISO 8601",
                      "updated_at": "ISO 8601"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 50,
                    "total": 5,
                    "total_pages": 1
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "items per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "description": "connecting a new platform happens via the dashboard OAuth flow; use DELETE to disconnect\n\n`inactive_reason` (1.51.0) says why a connection is inactive, in the words its `connection.expired` webhook carried (on Instagram and Facebook that includes Meta's Graph code, subcode, and message). text for people to read, not a value to branch on: `meta_deauthorize` is the only fixed value. `null` while the connection is live, and on a connection retired before 10/20/2026.\n\nevery connection that has not been removed is listed, including dead ones. `is_active` is false once the token is invalidated (the moment the `connection.expired` webhook fires) and true again if the connection recovers (`connection.restored`, within 72 hours). read `is_active` to decide whether a connection works, not `expires_at` - that is the access token's own expiry, which dropspace refreshes routinely."
      }
    },
    "/connections/{platform}": {
      "delete": {
        "tags": [
          "connections"
        ],
        "summary": "disconnect an OAuth platform connection (or a single account on it). `:platform` is the `platform` field from GET /connections (e.g. twitter, facebook)",
        "operationId": "deleteConnection",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/MessageResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "message": "twitter disconnected successfully"
                  }
                }
              }
            }
          },
          "404": {
            "description": "PLATFORM_001: connection not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "PLATFORM_004: unable to disconnect - please try again",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "platform",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "platform"
          },
          {
            "name": "account_id",
            "in": "query",
            "required": false,
            "description": "optional query param: disconnect only THIS account (its `entity_id` from GET /connections) instead of the whole platform. supported on instagram/tiktok/youtube/twitter/reddit; disconnecting the primary promotes another connected account to primary so your posting keys stay valid",
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "reconnect by re-running the OAuth flow from the dashboard or the in-app connect button\n\nomit `account_id` to disconnect every account on the platform; pass it to remove just one"
      }
    },
    "/connections/{platform}/profile": {
      "patch": {
        "tags": [
          "connections"
        ],
        "summary": "edit the connected account's profile on the platform. body: `{ \"description\": \"<text>\" }`. youtube only today - sets the channel description (max 1,000 characters; an empty string clears it). instagram's api can read a profile but not write it, facebook page \"about\" needs a permission dropspace does not hold, and tiktok / x / linkedin expose no profile write - those answer 400 with the reason. requires the write scope.",
        "operationId": "updateConnectionProfile",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/ConnectionProfile"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "platform": "youtube",
                    "description": "weekly drops, behind the scenes, and launch-day streams."
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: platform can't edit the profile (detail in message)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "PLATFORM_001: platform not connected",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "platform",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "platform"
          }
        ],
        "description": "the change is made on youtube itself via channels.update (50 quota units); the stored profile in GET /connections is refreshed at the same time."
      }
    },
    "/dropspace/status": {
      "get": {
        "tags": [
          "dropspace"
        ],
        "summary": "check which official dropspace accounts are connected",
        "operationId": "getDropspaceStatus",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/DropspaceStatus"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "platforms": [
                      {
                        "platform": "facebook",
                        "connected": true,
                        "account_name": "dropspace"
                      },
                      {
                        "platform": "linkedin",
                        "connected": true,
                        "account_name": "dropspace"
                      },
                      {
                        "platform": "twitter",
                        "connected": true,
                        "account_name": "@dropspace"
                      },
                      {
                        "platform": "instagram",
                        "connected": true,
                        "account_name": "@dropspace"
                      },
                      {
                        "platform": "tiktok",
                        "connected": false
                      },
                      {
                        "platform": "youtube",
                        "connected": false
                      }
                    ],
                    "connected_platforms": [
                      "facebook",
                      "linkedin",
                      "twitter",
                      "instagram"
                    ],
                    "timestamp": "ISO 8601"
                  }
                }
              }
            }
          }
        },
        "description": "always returns all 7 auto-post platforms in canonical order\n\naccount_name is only present when connected and account info exists\n\nconnected_platforms lists valid values for the dropspace_platforms field when creating launches\n\nchecks is_active flag and token expiry from the database - does not perform live health checks"
      }
    },
    "/keys/me": {
      "get": {
        "tags": [
          "API keys"
        ],
        "summary": "get the current API key's info",
        "operationId": "getKeyMe",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/ApiKey"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "name": "my integration",
                    "key_prefix": "ds_live_abc...",
                    "scopes": [
                      "read",
                      "write",
                      "generate",
                      "send"
                    ],
                    "created_at": "ISO 8601"
                  }
                }
              }
            }
          }
        },
        "description": "no scope required - any valid API key can check its own permissions"
      }
    },
    "/keys": {
      "get": {
        "tags": [
          "API keys"
        ],
        "summary": "list all API keys",
        "operationId": "listKeys",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKey"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "uuid",
                      "name": "my integration",
                      "key_prefix": "ds_live_abc...",
                      "scopes": [
                        "read",
                        "write",
                        "generate",
                        "send"
                      ],
                      "last_used_at": "ISO 8601 | null",
                      "revoked_at": "ISO 8601 | null",
                      "created_at": "ISO 8601"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "API keys"
        ],
        "summary": "create a new API key (max 10)",
        "operationId": "createKey",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CreateApiKeyResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "key": "ds_live_abc123...",
                    "api_key": {
                      "id": "uuid",
                      "name": "my integration",
                      "key_prefix": "ds_live_abc...",
                      "scopes": [
                        "read",
                        "write",
                        "generate",
                        "send"
                      ],
                      "created_at": "ISO 8601"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "key name"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "permission scopes. available: read, write, generate, send, admin. defaults to ['read','write'] when omitted - pass the full list explicitly if the key needs 'generate', 'send', or 'admin'."
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "description": "the full key is shown only once - store it securely"
      }
    },
    "/keys/{id}": {
      "patch": {
        "tags": [
          "API keys"
        ],
        "summary": "rename an API key",
        "operationId": "updateKey",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/ApiKey"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "name": "renamed key",
                    "key_prefix": "ds_live_abc...",
                    "last_used_at": "ISO 8601 | null",
                    "revoked_at": "ISO 8601 | null",
                    "created_at": "ISO 8601"
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: api key not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "SERVER_009: an api key with this name already exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "new key name"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "API keys"
        ],
        "summary": "revoke an API key",
        "operationId": "deleteKey",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "204": {
            "description": "no content"
          },
          "404": {
            "description": "SERVER_003: api key not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/keys/{id}/rotate": {
      "post": {
        "tags": [
          "API keys"
        ],
        "summary": "rotate an API key — issues a replacement and revokes the old one. the new raw key is returned exactly ONCE in this response and is never retrievable again, so store it before the call returns.",
        "operationId": "rotateKey",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CreateApiKeyResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "key": "ds_live_...",
                    "api_key": {
                      "id": "uuid",
                      "name": "string",
                      "key_prefix": "ds_live_abcd",
                      "created_at": "ISO 8601"
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "requires the `admin` scope.\n\nthe previous key stops working as soon as this returns."
      }
    },
    "/webhooks": {
      "get": {
        "tags": [
          "webhooks"
        ],
        "summary": "list webhook endpoints",
        "operationId": "listWebhooks",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Webhook"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "uuid",
                      "url": "https://your-app.com/webhooks",
                      "events": [
                        "launch.completed",
                        "launch.failed",
                        "post.deleted"
                      ],
                      "active": true,
                      "created_at": "ISO 8601",
                      "updated_at": "ISO 8601",
                      "consecutive_failures": 0,
                      "disabled_at": null,
                      "disabled_reason": null
                    }
                  ]
                }
              }
            }
          }
        },
        "description": "after 10 consecutive failed delivery attempts the endpoint is auto-disabled (active: false, disabled_reason set) and the account owner is emailed\n\nre-enable via PATCH /webhooks/:id with { \"active\": true }. this resets the failure counter"
      },
      "post": {
        "tags": [
          "webhooks"
        ],
        "summary": "create a webhook endpoint (max 10)",
        "operationId": "createWebhook",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "url": "https://your-app.com/webhooks",
                    "events": [
                      "launch.completed",
                      "launch.failed",
                      "post.deleted"
                    ],
                    "secret": "a1b2c3d4...",
                    "active": true,
                    "consecutive_failures": 0,
                    "disabled_at": null,
                    "disabled_reason": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: invalid webhook url or events; SERVER_002: maximum 10 webhook endpoints allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "webhook delivery URL (public https). a Slack incoming webhook URL (https://hooks.slack.com/services/...) receives each event as a readable Slack message instead of the signed JSON envelope"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "event types to subscribe to"
                  }
                },
                "required": [
                  "url",
                  "events"
                ]
              }
            }
          }
        },
        "description": "the secret is shown only once - store it securely for signature verification\n\navailable events: \"launch.completed\" (launch finished publishing), \"launch.failed\" (launch failed to publish), \"launch.partial\" (launch partially succeeded), \"media.ready\" (media generation completed), \"persona.analyzed\" (persona analysis completed), \"post.deleted\" (a published post was detected as deleted from its platform), \"recommendation.created\" (new recommendations were generated for the account), \"connection.expired\" (a connected account's token was invalidated and needs reauth), \"connection.restored\" (an expired connection is live again after a successful refresh - no reconnect needed)\n\nlaunch.completed / launch.partial / launch.failed payload: { \"event\": \"launch.completed\", \"data\": { \"launch_id\": \"uuid\", \"launch_name\": \"...\", \"platforms\": [ { \"platform\": \"tiktok\", \"status\": \"success\", \"post_url\": null, \"error_message\": null, \"pending\": false, \"publish_mode\": \"draft\", \"caption\": \"the text to paste\", \"media_type\": \"video\" } ] } } - publish_mode is \"direct\", or \"draft\" for a TikTok draft that sits in the creator's inbox until they post it from the TikTok app; caption then carries the composed text and is null otherwise; media_type is \"video\" or \"photo\" for a draft (null otherwise): TikTok drops a video draft's caption, so the creator pastes it, and keeps a photo draft's; pending is true while a post is accepted but not yet live, and the event fires again with the final post_url; a TikTok draft that TikTok is still processing is also pending, and the event fires again when it reaches the inbox (pending false), or as launch.partial / launch.failed if TikTok rejects it\n\npost.deleted payload: { \"event\": \"post.deleted\", \"data\": { \"launch_id\": \"uuid\", \"platform\": \"twitter\", \"post_url\": \"https://...\", \"post_id\": \"12345\", \"deletion_reason\": \"not_found\", \"detected_at\": \"2025-01-15T10:30:00Z\" } }\n\nconnection.expired payload: { \"event\": \"connection.expired\", \"data\": { \"platform\": \"instagram\", \"reason\": \"token_refresh_failed\", \"detected_at\": \"2026-02-18T12:00:00.000Z\" } }\n\nconnection.restored payload: { \"event\": \"connection.restored\", \"data\": { \"platform\": \"instagram\", \"reason\": \"token refresh succeeded after an earlier deactivation\", \"restored_at\": \"2026-09-08T19:30:00.000Z\" } } - dropspace re-tries a failed refresh for 72 hours after connection.expired; a connection still dead after that needs a reconnect\n\ndeletion_reason values: not_found, gone, creator_deleted, moderation_removed, account_deleted, spam_filtered"
      }
    },
    "/webhooks/{id}": {
      "get": {
        "tags": [
          "webhooks"
        ],
        "summary": "get a webhook endpoint",
        "operationId": "getWebhook",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "url": "https://your-app.com/webhooks",
                    "events": [
                      "launch.completed",
                      "launch.failed",
                      "post.deleted"
                    ],
                    "active": true,
                    "created_at": "ISO 8601",
                    "updated_at": "ISO 8601",
                    "consecutive_failures": 0,
                    "disabled_at": null,
                    "disabled_reason": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      },
      "patch": {
        "tags": [
          "webhooks"
        ],
        "summary": "update url, events, or active status",
        "operationId": "updateWebhook",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: invalid webhook url or events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "new webhook URL"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "new event subscriptions"
                  },
                  "active": {
                    "type": "boolean",
                    "description": "enable/disable endpoint"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "webhooks"
        ],
        "summary": "delete a webhook endpoint",
        "operationId": "deleteWebhook",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "204": {
            "description": "no content"
          },
          "404": {
            "description": "SERVER_003: webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/webhooks/{id}/test": {
      "post": {
        "tags": [
          "webhooks"
        ],
        "summary": "send a synthetic webhook.test event to the registered URL",
        "operationId": "testWebhook",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TestWebhookResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "success": true,
                    "delivery_id": "uuid",
                    "response_status": 200,
                    "response_body": "OK"
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "posts a `webhook.test` event signed with the webhook's secret to the registered URL\n\nreturns the receiver's response status and a (truncated) response body for debugging\n\ncreates a delivery row that shows up in `/webhooks/:id/deliveries`\n\n10s timeout: `response_status: 408` indicates the receiver didn't respond in time"
      }
    },
    "/webhooks/{id}/rotate-secret": {
      "post": {
        "tags": [
          "webhooks"
        ],
        "summary": "rotate the signing secret (new secret shown once)",
        "operationId": "rotateWebhookSecret",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/RotateSecretResponse"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "secret": "a1b2c3d4..."
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "description": "the new secret is shown only once - update your verification code immediately\n\nthe old secret becomes invalid immediately after rotation\n\nin-flight webhook deliveries (already queued) use the secret from enqueue time and are not affected"
      }
    },
    "/webhooks/{id}/deliveries": {
      "get": {
        "tags": [
          "webhooks"
        ],
        "summary": "list delivery attempts with pagination",
        "operationId": "getWebhookDeliveries",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookDelivery"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "page_size": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "page",
                        "page_size",
                        "total",
                        "total_pages"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "pagination"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "uuid",
                      "event_type": "launch.completed",
                      "status": "delivered|pending|failed",
                      "attempt_count": 1,
                      "response_status": 200,
                      "delivered_at": "ISO 8601",
                      "failed_at": null,
                      "next_retry_at": null,
                      "created_at": "ISO 8601"
                    }
                  ],
                  "pagination": {
                    "page": 1,
                    "page_size": 50,
                    "total": 12,
                    "total_pages": 1
                  }
                }
              }
            }
          },
          "404": {
            "description": "SERVER_003: webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "items per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "description": "`failed_at` is set on terminal failures (delivered_at and failed_at are mutually exclusive, mirroring iris). `next_retry_at` is null when QStash is handling retries opaquely."
      }
    },
    "/usage": {
      "get": {
        "tags": [
          "usage"
        ],
        "summary": "get plan limits and current usage",
        "operationId": "getUsage",
        "security": [
          {
            "apiKey": []
          },
          {
            "agentPaymentAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/UsageData"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "plan": "starter",
                    "billing_period": {
                      "start": "ISO 8601",
                      "end": "ISO 8601"
                    },
                    "limits": {
                      "launches_per_month": {
                        "limit": 50,
                        "used": 3,
                        "remaining": 47
                      },
                      "ai_images_per_month": {
                        "limit": 100,
                        "used": 12,
                        "remaining": 88
                      },
                      "ai_videos_per_month": {
                        "limit": 20,
                        "used": 5,
                        "remaining": 15
                      },
                      "personas": {
                        "limit": 10,
                        "used": 2,
                        "remaining": 8
                      },
                      "analyses_per_persona": {
                        "limit": 3
                      },
                      "regenerations_per_launch": {
                        "limit": 5
                      }
                    },
                    "features": {
                      "can_connect_own_accounts": true,
                      "can_post_to_official_accounts": true,
                      "allowed_platforms": [
                        "facebook",
                        "linkedin",
                        "twitter",
                        "reddit",
                        "instagram",
                        "tiktok",
                        "youtube"
                      ]
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "payment required: agent payment auth (x402 or MPP). launch creation beyond the free tier (5/month) costs $0.55 via x402 (crypto) or $0.60 via MPP (card). Authoritative x402 wallet challenge ships in the PAYMENT-REQUIRED header per x402 v2 spec; the body x402 block is a convenience for integrators inspecting JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "PAYMENT_001"
                        },
                        "message": {
                          "type": "string",
                          "example": "payment required: $0.55 USDC per launch (x402, 5 free/month) or $0.60 per launch (MPP)"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    },
                    "x402": {
                      "type": "object",
                      "description": "x402 protocol metadata (mirrors PAYMENT-REQUIRED header content)",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 2
                        },
                        "scheme": {
                          "type": "string",
                          "example": "exact"
                        },
                        "network": {
                          "type": "string",
                          "example": "base-mainnet"
                        },
                        "asset": {
                          "type": "string",
                          "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "description": "USDC contract address on Base"
                        },
                        "asset_name": {
                          "type": "string",
                          "example": "USDC"
                        },
                        "amount_atomic": {
                          "type": "string",
                          "example": "550000",
                          "description": "USDC amount in atomic units (6 decimals)"
                        },
                        "price_usd": {
                          "type": "string",
                          "example": "0.55"
                        },
                        "pay_to": {
                          "type": "string",
                          "description": "receiver wallet address"
                        },
                        "resource": {
                          "type": "string",
                          "example": "POST /launches"
                        },
                        "resource_url": {
                          "type": "string",
                          "example": "https://api.dropspace.dev/launches",
                          "description": "canonical URL wallets sign EIP-712 against"
                        },
                        "max_timeout_seconds": {
                          "type": "integer",
                          "example": 300
                        }
                      }
                    },
                    "mpp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 1
                        },
                        "method": {
                          "type": "string",
                          "example": "stripe"
                        },
                        "intent": {
                          "type": "string",
                          "example": "charge"
                        },
                        "currency": {
                          "type": "string",
                          "example": "usd"
                        },
                        "amount_cents": {
                          "type": "integer",
                          "example": 60
                        },
                        "resource": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "description": "limit and remaining can be \"unlimited\" (string) instead of a number for higher-tier plans\n\npersonas is a lifetime limit (not per billing period)\n\nanalyses_per_persona and regenerations_per_launch are per-resource limits (no used/remaining tracking)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "required": true,
            "description": "API key (Bearer ds_live_...) or x402 payment header (PAYMENT-SIGNATURE/X-PAYMENT, base64 challenge response).",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/recap": {
      "get": {
        "tags": [
          "recap"
        ],
        "summary": "get your 30-day posting recap: posts, launches, posts per platform, engagement totals, and the top post",
        "operationId": "getRecap",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Recap"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "period_start": "ISO 8601",
                    "period_end": "ISO 8601",
                    "posts": 42,
                    "launches": 12,
                    "platforms": [
                      {
                        "platform": "instagram",
                        "posts": 18
                      },
                      {
                        "platform": "tiktok",
                        "posts": 14
                      }
                    ],
                    "totals": {
                      "likes": 930,
                      "comments": 71,
                      "shares": 40,
                      "impressions": 51200
                    },
                    "posts_with_impressions": 37,
                    "top_post": {
                      "platform": "instagram",
                      "post_url": "https://www.instagram.com/reel/...",
                      "likes": 412,
                      "comments": 18,
                      "shares": 9,
                      "impressions": 20100
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "AUTH_002: the creator is paused, or its partner is suspended (partner-managed accounts only)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "description": "the window is the 30 days before the request. it is not a billing period and takes no parameters\n\ncounts successful posts from your own connected accounts. posts sent through a dropspace official account and posts you removed are left out\n\nengagement comes from the metrics dropspace last collected for each post, so it can trail the platform by a few hours\n\ntotals.impressions sums only the posts whose impressions are known (posts_with_impressions). when that is below posts, read it as a floor\n\ntop_post is the post with the most likes + comments + shares, or null when no post has any\n\nread-only. a public share link for the recap is created in the app, at /recap"
      }
    },
    "/affiliate": {
      "get": {
        "tags": [
          "affiliate"
        ],
        "summary": "get your affiliate status, link, sign-up count, and commission totals",
        "operationId": "getAffiliate",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Affiliate"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "status": "approved",
                    "code": "yourname",
                    "link": "https://www.dropspace.dev/?via=yourname",
                    "referrals": 7,
                    "commissions": {
                      "pending_cents": 1740,
                      "payable_cents": 870,
                      "paid_out_cents": 2610
                    },
                    "terms": {
                      "commission_rate_percent": 30,
                      "commission_window_months": 12,
                      "payout_hold_days": 30,
                      "referral_cookie_days": 30
                    }
                  }
                }
              }
            }
          }
        },
        "description": "status is \"none\" (never applied), \"pending\" (waiting for review), \"approved\", or \"rejected\". code is null when status is \"none\"\n\nlink is set only while status is approved. a pending or rejected code credits no sign-ups\n\nreferrals counts people who signed up within referral_cookie_days of first clicking your link\n\ncommissions are US cents. pending_cents is still inside the payout hold, payable_cents is past it and not yet paid, paid_out_cents has been sent. a full refund or a dispute cancels the commission on that payment, and a partial refund reduces it. a commission already paid out is not changed by a later refund\n\ncommissions come from card subscription payments on the web. App Store purchases and pay-per-launch agent payments earn none\n\nread-only. applying is done in the app, at /settings/affiliate; each application is reviewed, and payouts are sent by hand"
      }
    },
    "/credits": {
      "get": {
        "tags": [
          "credits"
        ],
        "summary": "get credit balance and available packs",
        "operationId": "getCredits",
        "security": [
          {
            "apiKey": []
          },
          {
            "agentPaymentAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CreditBalance"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "balance": 7,
                    "packs": [
                      {
                        "id": "pack_20",
                        "credits": 20,
                        "price_usd": "12.00"
                      }
                    ],
                    "purchase_endpoint": "POST /credits/purchase"
                  }
                }
              }
            }
          },
          "402": {
            "description": "payment required: agent payment auth (x402 or MPP). launch creation beyond the free tier (5/month) costs $0.55 via x402 (crypto) or $0.60 via MPP (card). Authoritative x402 wallet challenge ships in the PAYMENT-REQUIRED header per x402 v2 spec; the body x402 block is a convenience for integrators inspecting JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "PAYMENT_001"
                        },
                        "message": {
                          "type": "string",
                          "example": "payment required: $0.55 USDC per launch (x402, 5 free/month) or $0.60 per launch (MPP)"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    },
                    "x402": {
                      "type": "object",
                      "description": "x402 protocol metadata (mirrors PAYMENT-REQUIRED header content)",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 2
                        },
                        "scheme": {
                          "type": "string",
                          "example": "exact"
                        },
                        "network": {
                          "type": "string",
                          "example": "base-mainnet"
                        },
                        "asset": {
                          "type": "string",
                          "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "description": "USDC contract address on Base"
                        },
                        "asset_name": {
                          "type": "string",
                          "example": "USDC"
                        },
                        "amount_atomic": {
                          "type": "string",
                          "example": "550000",
                          "description": "USDC amount in atomic units (6 decimals)"
                        },
                        "price_usd": {
                          "type": "string",
                          "example": "0.55"
                        },
                        "pay_to": {
                          "type": "string",
                          "description": "receiver wallet address"
                        },
                        "resource": {
                          "type": "string",
                          "example": "POST /launches"
                        },
                        "resource_url": {
                          "type": "string",
                          "example": "https://api.dropspace.dev/launches",
                          "description": "canonical URL wallets sign EIP-712 against"
                        },
                        "max_timeout_seconds": {
                          "type": "integer",
                          "example": 300
                        }
                      }
                    },
                    "mpp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 1
                        },
                        "method": {
                          "type": "string",
                          "example": "stripe"
                        },
                        "intent": {
                          "type": "string",
                          "example": "charge"
                        },
                        "currency": {
                          "type": "string",
                          "example": "usd"
                        },
                        "amount_cents": {
                          "type": "integer",
                          "example": 60
                        },
                        "resource": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "description": "returns balance 0 for x402 wallets and API key users (credits are MPP-only)\n\nbalance is cached in Redis (5-min TTL) with database as source of truth",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "required": true,
            "description": "API key (Bearer ds_live_...) or x402 payment header (PAYMENT-SIGNATURE/X-PAYMENT, base64 challenge response).",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/credits/purchase": {
      "post": {
        "tags": [
          "credits"
        ],
        "summary": "purchase a credit pack via MPP payment",
        "operationId": "purchaseCredits",
        "security": [
          {
            "apiKey": []
          },
          {
            "agentPaymentAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CreditPurchaseResult"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "credits_added": 20,
                    "new_balance": 27,
                    "pack": {
                      "id": "pack_20",
                      "credits": 20,
                      "price_usd": "12.00"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "SERVER_002: x402 wallets cannot purchase credits (MPP only)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "payment required: agent payment auth (x402 or MPP). launch creation beyond the free tier (5/month) costs $0.55 via x402 (crypto) or $0.60 via MPP (card). Authoritative x402 wallet challenge ships in the PAYMENT-REQUIRED header per x402 v2 spec; the body x402 block is a convenience for integrators inspecting JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "PAYMENT_001"
                        },
                        "message": {
                          "type": "string",
                          "example": "payment required: $0.55 USDC per launch (x402, 5 free/month) or $0.60 per launch (MPP)"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    },
                    "x402": {
                      "type": "object",
                      "description": "x402 protocol metadata (mirrors PAYMENT-REQUIRED header content)",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 2
                        },
                        "scheme": {
                          "type": "string",
                          "example": "exact"
                        },
                        "network": {
                          "type": "string",
                          "example": "base-mainnet"
                        },
                        "asset": {
                          "type": "string",
                          "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "description": "USDC contract address on Base"
                        },
                        "asset_name": {
                          "type": "string",
                          "example": "USDC"
                        },
                        "amount_atomic": {
                          "type": "string",
                          "example": "550000",
                          "description": "USDC amount in atomic units (6 decimals)"
                        },
                        "price_usd": {
                          "type": "string",
                          "example": "0.55"
                        },
                        "pay_to": {
                          "type": "string",
                          "description": "receiver wallet address"
                        },
                        "resource": {
                          "type": "string",
                          "example": "POST /launches"
                        },
                        "resource_url": {
                          "type": "string",
                          "example": "https://api.dropspace.dev/launches",
                          "description": "canonical URL wallets sign EIP-712 against"
                        },
                        "max_timeout_seconds": {
                          "type": "integer",
                          "example": 300
                        }
                      }
                    },
                    "mpp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "integer",
                          "example": 1
                        },
                        "method": {
                          "type": "string",
                          "example": "stripe"
                        },
                        "intent": {
                          "type": "string",
                          "example": "charge"
                        },
                        "currency": {
                          "type": "string",
                          "example": "usd"
                        },
                        "amount_cents": {
                          "type": "integer",
                          "example": 60
                        },
                        "resource": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "PAYMENT_004: payment processed but credits could not be added (contact support)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pack": {
                    "type": "string",
                    "description": "credit pack ID to purchase (default: \"pack_20\")",
                    "default": "\"pack_20\""
                  }
                }
              }
            }
          }
        },
        "description": "MPP agents only - x402 wallets are rejected with 400 (crypto has low fees already)\n\nthe MPP credential must be for the pack price ($12.00 = 1200 cents), not the per-launch price\n\ncredits never expire and are deducted automatically when creating launches\n\nthe launch fee is charged once, when the launch is created, and covers the publishing attempt: a launch that ends partial or failed is not refunded. if creating the launch fails after payment, a used credit or free-tier launch is given back automatically; a per-launch x402 or MPP payment is not reversed automatically, so contact support with the request id.\n\nduplicate purchases with the same MPP credential are rejected (idempotent)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/launches/{id}/boost": {
      "post": {
        "tags": [
          "boosts"
        ],
        "summary": "create a paid boost on meta for an organic facebook or instagram launch (always PAUSED on create)",
        "operationId": "createBoost",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Boost"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "uuid",
                    "launch_id": "uuid",
                    "platform": "facebook",
                    "post_id": "<page_id>_<post_id>",
                    "status": "paused",
                    "objective": "engagement",
                    "daily_budget_cents": 500,
                    "duration_days": 3,
                    "meta_ad_account_id": "act_123",
                    "meta_campaign_id": "1234567890",
                    "meta_adset_id": "1234567891",
                    "meta_ad_id": "1234567892",
                    "impressions": null,
                    "clicks": null,
                    "reach": null,
                    "link_clicks": null,
                    "total_spend_cents": null,
                    "stop_reason": null,
                    "created_at": "ISO 8601",
                    "activated_at": null,
                    "ended_at": null
                  }
                }
              }
            }
          },
          "403": {
            "description": "ADS_002: facebook ads_management scope not granted; reauthorize with ads scopes; PLATFORM_001: facebook account not connected",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "ADS_007: launch has no successful facebook post to boost. publish to facebook first; ADS_001: no active facebook ad account found; set one up in meta business manager",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "platform": {
                    "type": "string",
                    "enum": [
                      "facebook",
                      "instagram"
                    ],
                    "description": "ad platform: facebook or instagram. IG boost requires the user's IG business account to be linked to one of their connected facebook pages",
                    "default": "facebook"
                  },
                  "daily_budget_cents": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 10000,
                    "description": "daily ad budget in cents ($1 - $100 per day). billed by meta to the user's ad account."
                  },
                  "duration_days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 7,
                    "description": "boost duration in days"
                  },
                  "objective": {
                    "type": "string",
                    "enum": [
                      "engagement",
                      "traffic"
                    ],
                    "description": "engagement optimizes for reactions on the post; traffic optimizes for clicks on the link and needs a facebook link post, one published with a link preview and no photos or video (otherwise 409)",
                    "default": "engagement"
                  },
                  "stop_rules": {
                    "type": "string",
                    "description": "pause the boost on meta when its average cost per click passes max_cpc_cents (10-10000), checked after 5 clicks, or when spend reaches 3x the cap with no clicks. every running boost also pauses itself when click-through over 1,000+ impressions falls below half its first-day rate. a paused boost resumes with POST /launches/{id}/boost/{boostId}/activate within its original schedule; the cost rules then count only spend and clicks after the resume"
                  },
                  "ad_account_id": {
                    "type": "string",
                    "description": "explicit meta ad account id (e.g. \"act_123\"); defaults to the first active account"
                  }
                },
                "required": [
                  "daily_budget_cents",
                  "duration_days"
                ]
              }
            }
          }
        },
        "description": "requires the launch to have a successful facebook post (post_id available in posting_logs).\n\nboost is created in PAUSED status. call POST /launches/{id}/boost/{boost_id}/activate to start spending.\n\ncreative reuses the existing organic post via object_story_id, so no creative upload is required.\n\nmeta enforces ad spend on the user's ad account. dropspace never holds card data for ad budgets."
      },
      "get": {
        "tags": [
          "boosts"
        ],
        "summary": "list all boosts attached to a launch",
        "operationId": "listBoosts",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Boost"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "uuid",
                      "launch_id": "uuid",
                      "status": "active",
                      "daily_budget_cents": 500,
                      "duration_days": 3,
                      "impressions": 4320,
                      "clicks": 87,
                      "reach": 3211,
                      "total_spend_cents": 1230
                    }
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          }
        ]
      }
    },
    "/launches/{id}/boost/{boost_id}": {
      "get": {
        "tags": [
          "boosts"
        ],
        "summary": "fetch a single boost with the latest performance metrics",
        "operationId": "getBoost",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Boost"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          },
          {
            "name": "boost_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "boost_id"
          }
        ]
      },
      "delete": {
        "tags": [
          "boosts"
        ],
        "summary": "cancel a boost: deletes the campaign on meta and soft-deletes the record",
        "operationId": "deleteBoost",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Boost"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          },
          {
            "name": "boost_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "boost_id"
          }
        ],
        "description": "idempotent: canceling a boost already in a terminal state returns the current row unchanged.\n\nif meta-side DELETE fails, the dropspace row is still soft-deleted (manual cleanup may be needed)."
      }
    },
    "/launches/{id}/boost/{boost_id}/activate": {
      "post": {
        "tags": [
          "boosts"
        ],
        "summary": "flip a PAUSED boost to ACTIVE on meta. ad spend begins immediately",
        "operationId": "activateBoost",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Boost"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "ADS_006: boost is already active; SERVER_009: cannot activate a boost in a terminal status (canceled / completed / failed)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string",
                          "description": "correlation id for support tickets / Sentry; also returned in X-Request-ID header"
                        },
                        "field": {
                          "type": "string",
                          "description": "validation-error field marker (when applicable)"
                        },
                        "details": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "requestId"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "error"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "id"
          },
          {
            "name": "boost_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "boost_id"
          }
        ],
        "description": "no payment required: boost was already paid for at create time.\n\nflips campaign → ad set → ad in order so the ad inherits ACTIVE status correctly."
      }
    },
    "/changelog": {
      "get": {
        "tags": [
          "changelog"
        ],
        "summary": "release history newest-first: version, date, type (feature/fix/breaking/docs), summary, and migration notes on breaking entries. public - the one-line X-Notice header on every response is the latest entry's summary; this is the structured history behind it",
        "operationId": "getChangelog",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChangelogEntry"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "version": "1.0.0",
                      "date": "2026-07-21",
                      "type": "feature",
                      "summary": "..."
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key starting with ds_live_. Create at https://www.dropspace.dev/settings under API keys."
      },
      "agentPaymentAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PAYMENT",
        "description": "agent payment auth. supports x402 (X-PAYMENT header with base64-encoded payment proof) and MPP (Authorization: Payment header with Stripe credential). x402 wallets get 5 free launches/month; beyond that, launch creation costs $0.55 via x402 (crypto) or $0.60 via MPP (card). see https://www.x402.org for x402 details."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "LAUNCH_001"
              },
              "message": {
                "type": "string",
                "example": "launch not found"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        }
      },
      "SubredditStandingBadge": {
        "type": "object",
        "properties": {
          "level": {
            "type": "string"
          },
          "tier": {
            "type": "string"
          },
          "promo_posts_here": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "contributions_here": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "promo_share": {
            "type": [
              "number",
              "null"
            ]
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "level",
          "tier",
          "promo_posts_here",
          "contributions_here",
          "promo_share",
          "reasons"
        ]
      },
      "EngagementThread": {
        "type": "object",
        "properties": {
          "subreddit": {
            "type": "string"
          },
          "thread_title": {
            "type": "string"
          },
          "thread_url": {
            "type": "string"
          },
          "thread_author": {
            "type": [
              "string",
              "null"
            ]
          },
          "relevance_score": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "subreddit",
          "thread_title",
          "thread_url",
          "thread_author",
          "relevance_score"
        ]
      },
      "QueueComment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "author_username": {
            "type": "string"
          },
          "author_display_name": {
            "type": "string"
          },
          "author_profile_image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "like_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reply_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "published_at": {
            "type": "string"
          },
          "hidden": {
            "type": "boolean"
          },
          "platform": {
            "type": "string"
          },
          "post_id": {
            "type": "string"
          },
          "post_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "launch_id": {
            "type": "string"
          },
          "launch_name": {
            "type": "string"
          },
          "kind": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "question",
              "feedback",
              "praise",
              "spam",
              "attack",
              "other"
            ]
          },
          "suggested_action": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "reply",
              "hide",
              "dismiss"
            ]
          },
          "reply_draft": {
            "type": [
              "string",
              "null"
            ]
          },
          "may_be_answered": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "text",
          "author_username",
          "author_display_name",
          "author_profile_image_url",
          "like_count",
          "reply_count",
          "published_at",
          "platform",
          "post_id",
          "post_url",
          "launch_id",
          "launch_name",
          "kind",
          "suggested_action",
          "reply_draft",
          "may_be_answered"
        ]
      },
      "SongReel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "song_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "snippet_start": {
            "type": "number"
          },
          "snippet_end": {
            "type": "number"
          },
          "style": {
            "type": "string",
            "enum": [
              "lower-third",
              "center-bold",
              "karaoke",
              "one-word",
              "caps-top"
            ]
          },
          "footage_mode": {
            "type": "string",
            "enum": [
              "clips",
              "none",
              "ai"
            ]
          },
          "clip_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "background": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "midnight",
              "sunset",
              "forest",
              "sand",
              "slate",
              "violet"
            ]
          },
          "hook_text": {
            "type": [
              "string",
              "null"
            ]
          },
          "rollout_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "variant_index": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "variant_note": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "footage_status": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "generating",
              "ready",
              "failed"
            ]
          },
          "lines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "number"
                },
                "end": {
                  "type": "number"
                },
                "text": {
                  "type": "string"
                }
              },
              "required": [
                "start",
                "end",
                "text"
              ]
            }
          },
          "render_status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "ready",
              "failed"
            ]
          },
          "render_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "video_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "thumbnail_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "duration_seconds": {
            "type": [
              "number",
              "null"
            ]
          },
          "media_library_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "launch_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "song_id",
          "title",
          "snippet_start",
          "snippet_end",
          "style",
          "footage_mode",
          "clip_ids",
          "background",
          "hook_text",
          "rollout_id",
          "variant_index",
          "variant_note",
          "ai_prompt",
          "footage_status",
          "lines",
          "render_status",
          "render_error",
          "video_url",
          "thumbnail_url",
          "duration_seconds",
          "media_library_id",
          "launch_id",
          "created_at",
          "updated_at"
        ]
      },
      "TrialReelProgramAccount": {
        "type": "object",
        "properties": {
          "connection_id": {
            "type": "string"
          },
          "username": {
            "type": [
              "string",
              "null"
            ]
          },
          "eligible": {
            "type": "boolean"
          },
          "ineligible_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "program": {
            "$ref": "#/components/schemas/TrialReelProgram"
          },
          "posting_hours": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            }
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrialReelQueueItem"
            }
          }
        },
        "required": [
          "connection_id",
          "username",
          "eligible",
          "ineligible_reason",
          "posting_hours",
          "items"
        ]
      },
      "TrialReelProgram": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "auto_approve": {
            "type": "boolean"
          },
          "reels_per_day": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "skip_caption_terms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "timezone": {
            "type": "string"
          },
          "edit_kinds": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "reshare",
                "background",
                "sticker",
                "subtitles",
                "hook"
              ]
            }
          },
          "last_scan_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_run_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_note": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "enabled",
          "auto_approve",
          "reels_per_day",
          "skip_caption_terms",
          "timezone",
          "edit_kinds",
          "last_scan_at",
          "last_run_at",
          "last_note"
        ]
      },
      "TrialReelQueueItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "posting",
              "posted",
              "won",
              "retired",
              "removed",
              "failed"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "reshare",
              "background",
              "sticker",
              "subtitles",
              "hook"
            ]
          },
          "prepare_status": {
            "type": "string",
            "enum": [
              "none",
              "pending",
              "running",
              "ready",
              "failed"
            ]
          },
          "prepare_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "variant_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "edit_summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "approved": {
            "type": "boolean"
          },
          "reason": {
            "type": "string"
          },
          "caption": {
            "type": "string"
          },
          "source": {
            "type": "object",
            "properties": {
              "media_id": {
                "type": "string"
              },
              "permalink": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "caption": {
                "type": "string"
              },
              "views": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "posted_at": {
                "type": "string"
              }
            },
            "required": [
              "media_id",
              "permalink",
              "caption",
              "views",
              "posted_at"
            ]
          },
          "win_target": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "launch_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "post_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "post_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "claimed_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "posted_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "checkpoints": {
            "type": "object",
            "properties": {
              "d1": {
                "$ref": "#/components/schemas/TrialReelCheckpoint"
              },
              "d3": {
                "$ref": "#/components/schemas/TrialReelCheckpoint"
              },
              "d7": {
                "$ref": "#/components/schemas/TrialReelCheckpoint"
              }
            }
          },
          "outcome_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "failure": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "kind",
          "prepare_status",
          "prepare_error",
          "variant_url",
          "edit_summary",
          "approved",
          "reason",
          "caption",
          "source",
          "win_target",
          "launch_id",
          "post_id",
          "post_url",
          "claimed_at",
          "posted_at",
          "checkpoints",
          "outcome_at",
          "failure",
          "created_at"
        ]
      },
      "TrialReelCheckpoint": {
        "type": "object",
        "properties": {
          "views": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reach": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "likes": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "comments": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "shares": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "saves": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "checked_at": {
            "type": "string"
          }
        },
        "required": [
          "views",
          "reach",
          "likes",
          "comments",
          "shares",
          "saves",
          "checked_at"
        ]
      },
      "TrialReelScanResult": {
        "type": "object",
        "properties": {
          "queued": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "rated": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "median_views": {
            "type": [
              "number",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "queued",
          "rated",
          "median_views",
          "note"
        ]
      },
      "AudiencePlatform": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string"
          },
          "entity_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "current": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "followers": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "following": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "media": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "captured_at": {
                "type": "string"
              }
            },
            "required": [
              "followers",
              "following",
              "media",
              "captured_at"
            ]
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AudienceSeriesPoint"
            }
          },
          "growth": {
            "type": "object",
            "properties": {
              "window_days": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "follower_delta": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "follower_pct": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "baseline_captured_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "effective_window_days": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "window_days",
              "follower_delta",
              "follower_pct",
              "baseline_captured_at",
              "effective_window_days"
            ]
          },
          "instagram_insights": {
            "$ref": "#/components/schemas/InstagramInsights"
          }
        },
        "required": [
          "platform",
          "entity_id",
          "current",
          "series",
          "growth"
        ]
      },
      "AudienceSeriesPoint": {
        "type": "object",
        "properties": {
          "captured_at": {
            "type": "string"
          },
          "followers": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "captured_at",
          "followers"
        ]
      },
      "InstagramInsights": {
        "type": "object",
        "properties": {
          "available": {
            "type": "boolean"
          },
          "unavailable_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "days": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InstagramInsightsDay"
            }
          },
          "followers_over_time": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "day": {
                  "type": "string"
                },
                "followers": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                }
              },
              "required": [
                "day",
                "followers"
              ]
            }
          },
          "totals": {
            "type": "object",
            "properties": {
              "follows": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "unfollows": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "net": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "non_follower_reach_share": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "follows",
              "unfollows",
              "net",
              "non_follower_reach_share"
            ]
          },
          "velocity": {
            "type": "object",
            "properties": {
              "this_week_net": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "this_week_pct": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "prior_weeks_avg_pct": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "trend": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "accelerating",
                  "slowing",
                  "steady"
                ]
              }
            },
            "required": [
              "this_week_net",
              "this_week_pct",
              "prior_weeks_avg_pct",
              "trend"
            ]
          },
          "profile_links_taps": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "days_pending": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "available",
          "unavailable_reason",
          "days",
          "followers_over_time",
          "totals",
          "velocity",
          "profile_links_taps",
          "days_pending"
        ]
      },
      "InstagramInsightsDay": {
        "type": "object",
        "properties": {
          "day": {
            "type": "string"
          },
          "follows": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "unfollows": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "net": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reach_followers": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reach_non_followers": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "settled": {
            "type": "boolean"
          }
        },
        "required": [
          "day",
          "follows",
          "unfollows",
          "net",
          "reach_followers",
          "reach_non_followers",
          "settled"
        ]
      },
      "TrialReel": {
        "type": "object",
        "properties": {
          "launch_id": {
            "type": "string"
          },
          "launch_name": {
            "type": "string"
          },
          "post_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "post_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "posted_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "graduation_strategy": {
            "type": [
              "string",
              "null"
            ]
          },
          "views": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reach": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "likes": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "comments": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "shares": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "saves": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "avg_watch_time_ms": {
            "type": [
              "number",
              "null"
            ]
          },
          "skip_rate": {
            "type": [
              "number",
              "null"
            ]
          },
          "metrics_fetched_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "launch_id",
          "launch_name",
          "post_id",
          "post_url",
          "posted_at",
          "graduation_strategy",
          "views",
          "reach",
          "likes",
          "comments",
          "shares",
          "saves",
          "avg_watch_time_ms",
          "skip_rate",
          "metrics_fetched_at"
        ]
      },
      "InstagramOnlineHoursAccount": {
        "type": "object",
        "properties": {
          "connection_id": {
            "type": "string"
          },
          "entity_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "username": {
            "type": [
              "string",
              "null"
            ]
          },
          "available": {
            "type": "boolean"
          },
          "unavailable_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "days_counted": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "hourly": {
            "minItems": 24,
            "maxItems": 24,
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "grid": {
            "minItems": 7,
            "maxItems": 7,
            "type": "array",
            "items": {
              "minItems": 24,
              "maxItems": 24,
              "type": "array",
              "items": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          },
          "best_hours": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BestHour"
            }
          }
        },
        "required": [
          "connection_id",
          "entity_id",
          "username",
          "available",
          "unavailable_reason",
          "days_counted",
          "hourly",
          "grid",
          "best_hours"
        ]
      },
      "BestHour": {
        "type": "object",
        "properties": {
          "hour": {
            "type": "integer",
            "minimum": 0,
            "maximum": 23
          },
          "avg_online": {
            "type": "number"
          }
        },
        "required": [
          "hour",
          "avg_online"
        ]
      },
      "InstagramDemographicsAccount": {
        "type": "object",
        "properties": {
          "connection_id": {
            "type": "string"
          },
          "entity_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "username": {
            "type": [
              "string",
              "null"
            ]
          },
          "followers": {
            "$ref": "#/components/schemas/DemographicsSection"
          },
          "engaged": {
            "$ref": "#/components/schemas/DemographicsSection"
          }
        },
        "required": [
          "connection_id",
          "entity_id",
          "username",
          "followers",
          "engaged"
        ]
      },
      "DemographicsSection": {
        "type": "object",
        "properties": {
          "available": {
            "type": "boolean"
          },
          "unavailable_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "age": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DemographicRow"
            }
          },
          "gender": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DemographicRow"
            }
          },
          "country": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DemographicRow"
            }
          },
          "city": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DemographicRow"
            }
          },
          "total": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "available",
          "unavailable_reason",
          "age",
          "gender",
          "country",
          "city",
          "total"
        ]
      },
      "DemographicRow": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "value",
          "count"
        ]
      },
      "ReelsReadAccount": {
        "type": "object",
        "properties": {
          "connection_id": {
            "type": "string"
          },
          "username": {
            "type": [
              "string",
              "null"
            ]
          },
          "read": {
            "$ref": "#/components/schemas/ReelsRead"
          },
          "next_refresh_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "connection_id",
          "username",
          "next_refresh_at"
        ]
      },
      "ReelsRead": {
        "type": "object",
        "properties": {
          "connection_id": {
            "type": "string"
          },
          "username": {
            "type": [
              "string",
              "null"
            ]
          },
          "generated_at": {
            "type": "string"
          },
          "window_days": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reel_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "oldest_posted_at": {
            "type": "string"
          },
          "tiers": {
            "type": "object",
            "properties": {
              "top": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReelStat"
                }
              },
              "middle": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReelStat"
                }
              },
              "bottom": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReelStat"
                }
              }
            },
            "required": [
              "top",
              "middle",
              "bottom"
            ]
          },
          "read": {
            "type": "object",
            "properties": {
              "summary": {
                "type": "string"
              },
              "working": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReelsReadFinding"
                }
              },
              "not_working": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReelsReadFinding"
                }
              },
              "next": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "summary",
              "working",
              "not_working",
              "next"
            ]
          },
          "model": {
            "type": "string"
          }
        },
        "required": [
          "connection_id",
          "username",
          "generated_at",
          "window_days",
          "reel_count",
          "oldest_posted_at",
          "tiers",
          "read",
          "model"
        ]
      },
      "ReelStat": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "permalink": {
            "type": [
              "string",
              "null"
            ]
          },
          "posted_at": {
            "type": "string"
          },
          "caption": {
            "type": "string"
          },
          "views": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reach": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "likes": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "comments": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "shares": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "saves": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "avg_watch_time_ms": {
            "type": [
              "number",
              "null"
            ]
          },
          "skip_rate": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "permalink",
          "posted_at",
          "caption",
          "views",
          "reach",
          "likes",
          "comments",
          "shares",
          "saves",
          "avg_watch_time_ms",
          "skip_rate"
        ]
      },
      "ReelsReadFinding": {
        "type": "object",
        "properties": {
          "pattern": {
            "type": "string"
          },
          "evidence": {
            "type": "string"
          }
        },
        "required": [
          "pattern",
          "evidence"
        ]
      },
      "BrandKit": {
        "type": "object",
        "properties": {
          "text_color": {
            "type": "string"
          },
          "outline_color": {
            "type": "string"
          },
          "logo_url": {
            "type": "string"
          },
          "logo_position": {
            "type": "string"
          }
        }
      },
      "UsageLimitEntry": {
        "type": "object",
        "properties": {
          "limit": {
            "$ref": "#/components/schemas/UsageLimit"
          },
          "used": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "remaining": {
            "$ref": "#/components/schemas/UsageLimit"
          }
        },
        "required": [
          "limit",
          "used",
          "remaining"
        ]
      },
      "UsageLimit": {
        "anyOf": [
          {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          {
            "type": "string",
            "const": "unlimited"
          }
        ]
      },
      "UsageLimitOnly": {
        "type": "object",
        "properties": {
          "limit": {
            "$ref": "#/components/schemas/UsageLimit"
          }
        },
        "required": [
          "limit"
        ]
      },
      "BoostStopRules": {
        "type": "object",
        "properties": {
          "max_cpc_cents": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        }
      },
      "LaunchCommentsPost": {
        "type": "object",
        "properties": {
          "post_id": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "post_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "posted_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "unsupported",
              "comments_disabled",
              "post_deleted",
              "unavailable"
            ]
          },
          "detail": {
            "type": [
              "string",
              "null"
            ]
          },
          "comments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PostComment"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "post_id",
          "platform",
          "post_url",
          "posted_at",
          "status",
          "detail",
          "comments",
          "next_cursor"
        ]
      },
      "PostComment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "author_username": {
            "type": "string"
          },
          "author_display_name": {
            "type": "string"
          },
          "author_profile_image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "like_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reply_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "published_at": {
            "type": "string"
          },
          "hidden": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "text",
          "author_username",
          "author_display_name",
          "author_profile_image_url",
          "like_count",
          "reply_count",
          "published_at"
        ]
      },
      "AutopilotPlatformSettings": {
        "type": "object",
        "properties": {
          "tiktok": {
            "$ref": "#/components/schemas/AutopilotTikTokSettings"
          },
          "youtube": {
            "$ref": "#/components/schemas/AutopilotYouTubeSettings"
          }
        }
      },
      "AutopilotTikTokSettings": {
        "type": "object",
        "properties": {
          "privacy_level": {
            "type": "string",
            "enum": [
              "PUBLIC_TO_EVERYONE",
              "MUTUAL_FOLLOW_FRIENDS",
              "FOLLOWER_OF_CREATOR",
              "SELF_ONLY"
            ]
          },
          "allow_comments": {
            "type": "boolean"
          },
          "allow_duet": {
            "type": "boolean"
          },
          "allow_stitch": {
            "type": "boolean"
          },
          "is_commercial": {
            "type": "boolean"
          },
          "is_your_brand": {
            "type": "boolean"
          },
          "is_branded_content": {
            "type": "boolean"
          }
        }
      },
      "AutopilotYouTubeSettings": {
        "type": "object",
        "properties": {
          "privacy_status": {
            "type": "string",
            "enum": [
              "public",
              "unlisted",
              "private"
            ]
          },
          "made_for_kids": {
            "type": "boolean"
          }
        }
      },
      "ChangelogEntry": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "feature",
              "fix",
              "breaking",
              "docs"
            ]
          },
          "summary": {
            "type": "string"
          },
          "migration": {
            "type": "string"
          }
        },
        "required": [
          "version",
          "date",
          "type",
          "summary"
        ]
      },
      "Launch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scheduled_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "product_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "product_description": {
            "type": [
              "string",
              "null"
            ]
          },
          "persona_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "media_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "dropspace_platforms": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "user_platform_accounts": {
            "type": [
              "object",
              "null"
            ],
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            }
          },
          "platform_contents": {
            "type": [
              "object",
              "null"
            ],
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "media_assets": {
            "type": [
              "array",
              "null"
            ],
            "items": {}
          },
          "posting_status": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string"
                },
                "account_type": {
                  "type": "string"
                },
                "post_url": {
                  "type": "string"
                },
                "error_message": {
                  "type": "string"
                },
                "posted_at": {
                  "type": "string"
                }
              },
              "required": [
                "status"
              ]
            }
          },
          "error_message": {
            "type": [
              "string",
              "null"
            ]
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "regenerations_used": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "id",
          "name",
          "status",
          "platforms",
          "scheduled_date",
          "product_url",
          "product_description",
          "persona_id",
          "media_mode",
          "dropspace_platforms",
          "user_platform_accounts",
          "platform_contents",
          "media_assets",
          "error_message",
          "started_at",
          "completed_at",
          "created_at",
          "updated_at"
        ]
      },
      "LaunchListItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scheduled_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "product_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "product_description": {
            "type": [
              "string",
              "null"
            ]
          },
          "persona_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "media_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "dropspace_platforms": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "user_platform_accounts": {
            "type": [
              "object",
              "null"
            ],
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            }
          },
          "media_assets": {
            "type": [
              "array",
              "null"
            ],
            "items": {}
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "status",
          "platforms",
          "scheduled_date",
          "product_url",
          "product_description",
          "persona_id",
          "media_mode",
          "dropspace_platforms",
          "user_platform_accounts",
          "media_assets",
          "created_at",
          "updated_at"
        ]
      },
      "PostingStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "account_type": {
            "type": "string"
          },
          "post_url": {
            "type": "string"
          },
          "error_message": {
            "type": "string"
          },
          "posted_at": {
            "type": "string"
          }
        },
        "required": [
          "status"
        ]
      },
      "PostingLog": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "post_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "post_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "error_message": {
            "type": [
              "string",
              "null"
            ]
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "attempt_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "posted_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "platform",
          "status",
          "post_url",
          "post_id",
          "error_message",
          "error_code",
          "attempt_count",
          "posted_at",
          "created_at"
        ]
      },
      "LaunchStatusDetail": {
        "type": "object",
        "properties": {
          "launch_id": {
            "type": "string"
          },
          "launch_status": {
            "type": "string"
          },
          "posting_logs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "platform": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "post_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "post_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "error_message": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "error_code": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "attempt_count": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                "posted_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "created_at": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "platform",
                "status",
                "post_url",
                "post_id",
                "error_message",
                "error_code",
                "attempt_count",
                "posted_at",
                "created_at"
              ]
            }
          }
        },
        "required": [
          "launch_id",
          "launch_status",
          "posting_logs"
        ]
      },
      "LaunchDestination": {
        "type": "object",
        "properties": {
          "posting_log_id": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "account_type": {
            "type": "string"
          },
          "subreddit": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "post_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "post_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "error_message": {
            "type": [
              "string",
              "null"
            ]
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "attempt_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "posted_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "posting_log_id",
          "platform",
          "account_type",
          "subreddit",
          "status",
          "post_url",
          "post_id",
          "error_message",
          "error_code",
          "attempt_count",
          "posted_at",
          "created_at"
        ]
      },
      "SubredditSuggestions": {
        "type": "object",
        "properties": {
          "icp_summary": {
            "type": "string"
          },
          "suggestions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "subscribers": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                "over18": {
                  "type": "boolean"
                },
                "subreddit_type": {
                  "type": "string"
                },
                "promo_policy": {
                  "type": "string"
                },
                "promo_evidence": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "standing": {
                  "$ref": "#/components/schemas/SubredditStandingBadge"
                },
                "reason": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "title",
                "subscribers",
                "over18",
                "subreddit_type",
                "promo_policy",
                "promo_evidence",
                "standing",
                "reason"
              ]
            }
          }
        },
        "required": [
          "icp_summary",
          "suggestions"
        ]
      },
      "EngagementConfig": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "max_comments_per_day": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "max_comments_per_sub_per_day": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "min_gap_minutes": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "gate_passed": {
            "type": "boolean"
          },
          "account_username": {
            "type": [
              "string",
              "null"
            ]
          },
          "account_total_karma": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "persona_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "auto_approve": {
            "type": "boolean"
          }
        },
        "required": [
          "enabled",
          "max_comments_per_day",
          "max_comments_per_sub_per_day",
          "min_gap_minutes",
          "gate_passed",
          "account_username",
          "account_total_karma",
          "persona_id",
          "auto_approve"
        ]
      },
      "EngagementComment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "comment_kind": {
            "type": "string"
          },
          "subreddit": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "scheduled_for": {
            "type": [
              "string",
              "null"
            ]
          },
          "comment_permalink": {
            "type": [
              "string",
              "null"
            ]
          },
          "comment_score": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "error_message": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "target": {
            "$ref": "#/components/schemas/EngagementThread"
          }
        },
        "required": [
          "id",
          "comment_kind",
          "subreddit",
          "body",
          "status",
          "scheduled_for",
          "comment_permalink",
          "comment_score",
          "error_message",
          "created_at"
        ]
      },
      "CommentQueue": {
        "type": "object",
        "properties": {
          "comments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueueComment"
            }
          },
          "counts": {
            "type": "object",
            "properties": {
              "question": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "feedback": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "praise": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "spam": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "attack": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "other": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "unclassified": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "question",
              "feedback",
              "praise",
              "spam",
              "attack",
              "other",
              "unclassified"
            ]
          },
          "total_waiting": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "posts_read": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "posts_in_window": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "post_issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "platform": {
                  "type": "string"
                },
                "post_id": {
                  "type": "string"
                },
                "launch_id": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                }
              },
              "required": [
                "platform",
                "post_id",
                "launch_id",
                "detail"
              ]
            }
          },
          "window_days": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "as_of": {
            "type": "string"
          }
        },
        "required": [
          "comments",
          "counts",
          "total_waiting",
          "posts_read",
          "posts_in_window",
          "post_issues",
          "window_days",
          "as_of"
        ]
      },
      "CommentActionsResult": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "hide",
              "dismiss"
            ]
          },
          "succeeded": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "failed": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "platform": {
                  "type": "string"
                },
                "post_id": {
                  "type": "string"
                },
                "comment_id": {
                  "type": "string"
                },
                "ok": {
                  "type": "boolean"
                },
                "detail": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "platform",
                "post_id",
                "comment_id",
                "ok",
                "detail"
              ]
            }
          }
        },
        "required": [
          "action",
          "succeeded",
          "failed",
          "results"
        ]
      },
      "ReportSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "audit",
              "best_times",
              "winners",
              "other"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "mcp",
              "api"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "title",
          "kind",
          "source",
          "created_at"
        ]
      },
      "Report": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "audit",
              "best_times",
              "winners",
              "other"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "mcp",
              "api"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "title",
          "kind",
          "source",
          "created_at",
          "body"
        ]
      },
      "ReportDeletion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "deleted": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "id",
          "deleted"
        ]
      },
      "SongSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "upload",
              "link",
              "url"
            ]
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "ready",
              "failed"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "duration_seconds": {
            "type": [
              "number",
              "null"
            ]
          },
          "size_bytes": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "audio_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "lyrics_status": {
            "type": "string",
            "enum": [
              "none",
              "ready",
              "failed"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "title",
          "source",
          "source_url",
          "status",
          "error",
          "duration_seconds",
          "size_bytes",
          "audio_url",
          "lyrics_status",
          "created_at",
          "updated_at"
        ]
      },
      "Song": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "upload",
              "link",
              "url"
            ]
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "ready",
              "failed"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "duration_seconds": {
            "type": [
              "number",
              "null"
            ]
          },
          "size_bytes": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "audio_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "lyrics_status": {
            "type": "string",
            "enum": [
              "none",
              "ready",
              "failed"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "peaks": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "number"
            }
          }
        },
        "required": [
          "id",
          "title",
          "source",
          "source_url",
          "status",
          "error",
          "duration_seconds",
          "size_bytes",
          "audio_url",
          "lyrics_status",
          "created_at",
          "updated_at",
          "peaks"
        ]
      },
      "SongLyrics": {
        "type": "object",
        "properties": {
          "song_id": {
            "type": "string"
          },
          "language": {
            "type": [
              "string",
              "null"
            ]
          },
          "text": {
            "type": "string"
          },
          "words": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string"
                },
                "start": {
                  "type": "number"
                },
                "end": {
                  "type": "number"
                }
              },
              "required": [
                "text",
                "start",
                "end"
              ]
            }
          }
        },
        "required": [
          "song_id",
          "language",
          "text",
          "words"
        ]
      },
      "SongDeletion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "deleted": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "id",
          "deleted"
        ]
      },
      "SongReelDeletion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "deleted": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "id",
          "deleted"
        ]
      },
      "SongReelRollout": {
        "type": "object",
        "properties": {
          "rollout_id": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SongReel"
            }
          }
        },
        "required": [
          "rollout_id",
          "count",
          "reels"
        ]
      },
      "SceneClipJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "library",
              "link",
              "url"
            ]
          },
          "source_url": {
            "type": "string"
          },
          "source_title": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_media_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_duration_seconds": {
            "type": [
              "number",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "ready",
              "failed"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "attempts": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "clips_made": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "clips_added": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "clips": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "number"
                },
                "end": {
                  "type": "number"
                },
                "video_url": {
                  "type": "string"
                },
                "thumbnail_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "media_library_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "start",
                "end",
                "video_url",
                "thumbnail_url",
                "media_library_id"
              ]
            }
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "source",
          "source_url",
          "source_title",
          "source_media_id",
          "source_duration_seconds",
          "status",
          "error",
          "attempts",
          "clips_made",
          "clips_added",
          "clips",
          "note",
          "created_at",
          "updated_at"
        ]
      },
      "SceneClipJobDeletion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "deleted": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "id",
          "deleted"
        ]
      },
      "TrialReelPrograms": {
        "type": "object",
        "properties": {
          "accounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrialReelProgramAccount"
            }
          }
        },
        "required": [
          "accounts"
        ]
      },
      "TrialReelProgramUpdate": {
        "type": "object",
        "properties": {
          "program": {
            "$ref": "#/components/schemas/TrialReelProgram"
          },
          "scan": {
            "$ref": "#/components/schemas/TrialReelScanResult"
          }
        },
        "required": [
          "program"
        ]
      },
      "TrialReelApproveAllResult": {
        "type": "object",
        "properties": {
          "approved": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "approved"
        ]
      },
      "SubredditStanding": {
        "type": "object",
        "properties": {
          "subreddit": {
            "type": "string"
          },
          "tier": {
            "type": "string"
          },
          "comments_posted": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "comments_removed": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "karma_earned": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "paused_until": {
            "type": [
              "string",
              "null"
            ]
          },
          "pause_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_activity_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "subreddit",
          "tier",
          "comments_posted",
          "comments_removed",
          "karma_earned",
          "paused_until",
          "pause_reason",
          "last_activity_at"
        ]
      },
      "EngagementSweepResult": {
        "type": "object",
        "properties": {
          "drafted": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "skipped": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "drafted",
          "skipped"
        ]
      },
      "EngagementApproveResult": {
        "type": "object",
        "properties": {
          "scheduled_for": {
            "type": "string"
          }
        },
        "required": [
          "scheduled_for"
        ]
      },
      "EngagementRejectResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "status"
        ]
      },
      "EngagementSubreddit": {
        "type": "object",
        "properties": {
          "subreddit": {
            "type": "string"
          },
          "engagement_enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "subreddit",
          "engagement_enabled"
        ]
      },
      "LaunchAnalytics": {
        "type": "object",
        "properties": {
          "launch_id": {
            "type": "string"
          },
          "launch_name": {
            "type": "string"
          },
          "launch_status": {
            "type": "string"
          },
          "summary": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "successful": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "failed": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "pending": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "total",
              "successful",
              "failed",
              "pending"
            ]
          },
          "fetched_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "next_refresh_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "platform": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "post_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "post_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "posted_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "cache_status": {
                  "type": "string"
                },
                "is_deleted": {
                  "type": "boolean"
                },
                "deleted_detected_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "deletion_reason": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "metrics": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "tracked_clicks": {
                      "description": "clicks on the post's tracked link (launches created with track_links)",
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    }
                  },
                  "additionalProperties": {}
                }
              },
              "required": [
                "platform",
                "status",
                "post_url",
                "post_id",
                "posted_at",
                "metrics"
              ]
            }
          }
        },
        "required": [
          "launch_id",
          "launch_name",
          "launch_status",
          "summary",
          "fetched_at",
          "next_refresh_at",
          "platforms"
        ]
      },
      "Audience": {
        "type": "object",
        "properties": {
          "platforms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AudiencePlatform"
            }
          },
          "as_of": {
            "type": "string"
          }
        },
        "required": [
          "platforms",
          "as_of"
        ]
      },
      "TrialReelSummary": {
        "type": "object",
        "properties": {
          "totals": {
            "type": "object",
            "properties": {
              "trial_reels": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "views": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "reach": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "likes": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "comments": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "shares": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "saves": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "avg_watch_time_ms": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "skip_rate": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "trial_reels",
              "views",
              "reach",
              "likes",
              "comments",
              "shares",
              "saves",
              "avg_watch_time_ms",
              "skip_rate"
            ]
          },
          "followers_since_first": {
            "type": "object",
            "properties": {
              "net": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "since_day": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "days_counted": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "days_in_span": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "net",
              "since_day",
              "days_counted",
              "days_in_span"
            ]
          },
          "reels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrialReel"
            }
          }
        },
        "required": [
          "totals",
          "followers_since_first",
          "reels"
        ]
      },
      "BestPostingHours": {
        "type": "object",
        "properties": {
          "timezone": {
            "type": "string"
          },
          "accounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InstagramOnlineHoursAccount"
            }
          },
          "best_hours": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BestHour"
            }
          },
          "as_of": {
            "type": "string"
          }
        },
        "required": [
          "timezone",
          "accounts",
          "best_hours",
          "as_of"
        ]
      },
      "AudienceDemographics": {
        "type": "object",
        "properties": {
          "timeframe": {
            "type": "string",
            "enum": [
              "this_week",
              "this_month",
              "last_90_days"
            ]
          },
          "accounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InstagramDemographicsAccount"
            }
          },
          "as_of": {
            "type": "string"
          }
        },
        "required": [
          "timeframe",
          "accounts",
          "as_of"
        ]
      },
      "ReelsReadOverview": {
        "type": "object",
        "properties": {
          "accounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReelsReadAccount"
            }
          }
        },
        "required": [
          "accounts"
        ]
      },
      "ReelsReadResult": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "not_enough_reels",
              "unavailable"
            ]
          },
          "read": {
            "$ref": "#/components/schemas/ReelsRead"
          },
          "refreshed": {
            "type": "boolean"
          },
          "next_refresh_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "reel_count": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "needed": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "status",
          "refreshed",
          "next_refresh_at",
          "reel_count",
          "needed",
          "reason"
        ]
      },
      "Persona": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "persona_analysis": {},
          "persona_analysis_structured": {},
          "build_status": {
            "type": "string"
          },
          "build_progress": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "build_started_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "build_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_analyzed_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "custom_samples": {
            "type": "array",
            "items": {}
          },
          "twitter_samples": {
            "type": "array",
            "items": {}
          },
          "reddit_samples": {
            "type": "array",
            "items": {}
          },
          "facebook_samples": {
            "type": "array",
            "items": {}
          },
          "instagram_samples": {
            "type": "array",
            "items": {}
          },
          "tiktok_samples": {
            "type": "array",
            "items": {}
          },
          "linkedin_samples": {
            "type": "array",
            "items": {}
          },
          "brand_kit": {
            "$ref": "#/components/schemas/BrandKit"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "persona_analysis",
          "build_status",
          "build_progress",
          "build_started_at",
          "build_error",
          "last_analyzed_at",
          "created_at",
          "updated_at"
        ]
      },
      "MediaLibraryItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "image",
              "video"
            ]
          },
          "mime_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "width": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "height": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "size_bytes": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "thumbnail_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "filename": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "upload",
              "launch"
            ]
          },
          "use_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "url",
          "type",
          "mime_type",
          "width",
          "height",
          "size_bytes",
          "thumbnail_url",
          "filename",
          "description",
          "source",
          "use_count",
          "last_used_at",
          "created_at",
          "updated_at"
        ]
      },
      "MediaLibraryAddResult": {
        "type": "object",
        "properties": {
          "added": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "image",
                    "video"
                  ]
                },
                "mime_type": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "width": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                "height": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                "size_bytes": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                "thumbnail_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "filename": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "source": {
                  "type": "string",
                  "enum": [
                    "upload",
                    "launch"
                  ]
                },
                "use_count": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                "last_used_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "created_at": {
                  "type": "string"
                },
                "updated_at": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "url",
                "type",
                "mime_type",
                "width",
                "height",
                "size_bytes",
                "thumbnail_url",
                "filename",
                "description",
                "source",
                "use_count",
                "last_used_at",
                "created_at",
                "updated_at"
              ]
            }
          }
        },
        "required": [
          "added"
        ]
      },
      "MediaLibraryDeleteResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "deleted": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "id",
          "deleted"
        ]
      },
      "Connection": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "entity_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "account_info": {},
          "account_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_active": {
            "type": "boolean"
          },
          "inactive_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "platform",
          "entity_id",
          "account_info",
          "account_type",
          "is_active",
          "inactive_reason",
          "expires_at",
          "created_at",
          "updated_at"
        ]
      },
      "ConnectionProfile": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "required": [
          "platform",
          "description"
        ]
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "key_prefix": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "key_prefix",
          "scopes",
          "last_used_at",
          "revoked_at",
          "created_at"
        ]
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "secret": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "consecutive_failures": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "disabled_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "disabled_reason": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "url",
          "events",
          "active",
          "created_at",
          "updated_at",
          "consecutive_failures",
          "disabled_at",
          "disabled_reason"
        ]
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "webhook_id": {
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "attempt_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "response_status": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "response_body": {
            "type": [
              "string",
              "null"
            ]
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "failed_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "next_retry_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "webhook_id",
          "event_type",
          "status",
          "attempt_count",
          "response_status",
          "response_body",
          "delivered_at",
          "failed_at",
          "next_retry_at",
          "created_at"
        ]
      },
      "DropspaceStatus": {
        "type": "object",
        "properties": {
          "platforms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "platform": {
                  "type": "string"
                },
                "connected": {
                  "type": "boolean"
                },
                "account_name": {
                  "type": "string"
                }
              },
              "required": [
                "platform",
                "connected"
              ]
            }
          },
          "connected_platforms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "timestamp": {
            "type": "string"
          }
        },
        "required": [
          "platforms",
          "connected_platforms",
          "timestamp"
        ]
      },
      "UsageData": {
        "type": "object",
        "properties": {
          "plan": {
            "type": "string"
          },
          "billing_period": {
            "type": "object",
            "properties": {
              "start": {
                "type": "string"
              },
              "end": {
                "type": "string"
              }
            },
            "required": [
              "start",
              "end"
            ]
          },
          "limits": {
            "type": "object",
            "properties": {
              "launches_per_month": {
                "$ref": "#/components/schemas/UsageLimitEntry"
              },
              "ai_images_per_month": {
                "$ref": "#/components/schemas/UsageLimitEntry"
              },
              "ai_videos_per_month": {
                "$ref": "#/components/schemas/UsageLimitEntry"
              },
              "personas": {
                "$ref": "#/components/schemas/UsageLimitEntry"
              },
              "analyses_per_persona": {
                "$ref": "#/components/schemas/UsageLimitOnly"
              },
              "regenerations_per_launch": {
                "$ref": "#/components/schemas/UsageLimitOnly"
              }
            },
            "required": [
              "launches_per_month",
              "ai_images_per_month",
              "ai_videos_per_month",
              "personas",
              "analyses_per_persona",
              "regenerations_per_launch"
            ]
          },
          "features": {
            "type": "object",
            "properties": {
              "can_connect_own_accounts": {
                "type": "boolean"
              },
              "can_post_to_official_accounts": {
                "type": "boolean"
              },
              "allowed_platforms": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "can_connect_own_accounts",
              "can_post_to_official_accounts",
              "allowed_platforms"
            ]
          }
        },
        "required": [
          "plan",
          "billing_period",
          "limits",
          "features"
        ]
      },
      "Recap": {
        "type": "object",
        "properties": {
          "period_start": {
            "type": "string"
          },
          "period_end": {
            "type": "string"
          },
          "posts": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "launches": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "platform": {
                  "type": "string"
                },
                "posts": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                }
              },
              "required": [
                "platform",
                "posts"
              ]
            }
          },
          "totals": {
            "type": "object",
            "properties": {
              "likes": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "comments": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "shares": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "impressions": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "likes",
              "comments",
              "shares",
              "impressions"
            ]
          },
          "posts_with_impressions": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "top_post": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "platform": {
                "type": "string"
              },
              "post_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "likes": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "comments": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "shares": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "impressions": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "platform",
              "post_url",
              "likes",
              "comments",
              "shares",
              "impressions"
            ]
          }
        },
        "required": [
          "period_start",
          "period_end",
          "posts",
          "launches",
          "platforms",
          "totals",
          "posts_with_impressions",
          "top_post"
        ]
      },
      "Affiliate": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "none",
              "pending",
              "approved",
              "rejected"
            ]
          },
          "code": {
            "type": [
              "string",
              "null"
            ]
          },
          "link": {
            "type": [
              "string",
              "null"
            ]
          },
          "referrals": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "commissions": {
            "type": "object",
            "properties": {
              "pending_cents": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "payable_cents": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "paid_out_cents": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "pending_cents",
              "payable_cents",
              "paid_out_cents"
            ]
          },
          "terms": {
            "type": "object",
            "properties": {
              "commission_rate_percent": {
                "type": "number"
              },
              "commission_window_months": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "payout_hold_days": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "referral_cookie_days": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "commission_rate_percent",
              "commission_window_months",
              "payout_hold_days",
              "referral_cookie_days"
            ]
          }
        },
        "required": [
          "status",
          "code",
          "link",
          "referrals",
          "commissions",
          "terms"
        ]
      },
      "MediaGenerationJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "generation_type": {
            "type": "string"
          },
          "model_id": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "result_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "progress": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "error_message": {
            "type": [
              "string",
              "null"
            ]
          },
          "launch_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "reference_image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "generation_type",
          "model_id",
          "prompt",
          "result_url",
          "status",
          "progress",
          "error_message",
          "launch_id",
          "reference_image_url",
          "created_at",
          "completed_at"
        ]
      },
      "MediaGenerateResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "job_id": {
            "type": "string"
          },
          "fal_request_id": {
            "type": "string"
          },
          "generation_type": {
            "type": "string"
          },
          "usage": {
            "type": "object",
            "properties": {
              "used": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "limit": {
                "$ref": "#/components/schemas/UsageLimit"
              },
              "remaining": {
                "$ref": "#/components/schemas/UsageLimit"
              }
            },
            "required": [
              "used",
              "limit",
              "remaining"
            ]
          },
          "plan": {
            "type": "string"
          }
        },
        "required": [
          "status",
          "job_id",
          "fal_request_id",
          "generation_type",
          "usage",
          "plan"
        ]
      },
      "Notification": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "data": {},
          "read": {
            "type": "boolean"
          },
          "read_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "priority": {
            "type": "string"
          },
          "action_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "launch_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "title",
          "message",
          "data",
          "read",
          "read_at",
          "priority",
          "action_url",
          "launch_id",
          "created_at",
          "updated_at"
        ]
      },
      "Recommendation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "rec_type": {
            "type": "string",
            "enum": [
              "repost_winner",
              "cross_post",
              "boost_winner",
              "promote_winner",
              "pause_underperformer"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "applied",
              "dismissed",
              "expired"
            ]
          },
          "platform": {
            "type": "string"
          },
          "launch_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "posting_log_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "payload": {},
          "score": {
            "type": [
              "number",
              "null"
            ]
          },
          "baseline": {
            "type": [
              "number",
              "null"
            ]
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "applied_launch_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "applied_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "dismissed_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "rec_type",
          "status",
          "platform",
          "launch_id",
          "posting_log_id",
          "payload",
          "score",
          "baseline",
          "expires_at",
          "applied_launch_id",
          "applied_at",
          "dismissed_at",
          "created_at",
          "updated_at"
        ]
      },
      "RecommendationApplyResponse": {
        "type": "object",
        "properties": {
          "recommendation": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "rec_type": {
                "type": "string",
                "enum": [
                  "repost_winner",
                  "cross_post",
                  "boost_winner",
                  "promote_winner",
                  "pause_underperformer"
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "applied",
                  "dismissed",
                  "expired"
                ]
              },
              "platform": {
                "type": "string"
              },
              "launch_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "posting_log_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "payload": {},
              "score": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "baseline": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "expires_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "applied_launch_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "applied_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "dismissed_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "created_at": {
                "type": "string"
              },
              "updated_at": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "rec_type",
              "status",
              "platform",
              "launch_id",
              "posting_log_id",
              "payload",
              "score",
              "baseline",
              "expires_at",
              "applied_launch_id",
              "applied_at",
              "dismissed_at",
              "created_at",
              "updated_at"
            ]
          },
          "outcome": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "launch_draft",
                  "boost_created",
                  "autopilot_queued",
                  "directive_added"
                ]
              },
              "launch_id": {
                "type": "string"
              },
              "boost_id": {
                "type": "string"
              },
              "boost_status": {
                "type": "string"
              },
              "dedupe_key": {
                "type": "string"
              },
              "directive": {
                "type": "string"
              }
            },
            "required": [
              "kind"
            ]
          }
        },
        "required": [
          "recommendation",
          "outcome"
        ]
      },
      "Profile": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "full_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "avatar_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "role": {
            "type": "string"
          },
          "has_completed_onboarding": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "email",
          "full_name",
          "avatar_url",
          "role",
          "has_completed_onboarding",
          "created_at",
          "updated_at"
        ]
      },
      "NotificationSettings": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "email_enabled": {
            "type": "boolean"
          },
          "email_launch_completed": {
            "type": "boolean"
          },
          "email_launch_failed": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "user_id",
          "email_enabled",
          "email_launch_completed",
          "email_launch_failed",
          "created_at",
          "updated_at"
        ]
      },
      "MessageResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      },
      "DeletePostsResult": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "success": {
                  "type": "boolean"
                },
                "platform": {
                  "type": "string"
                },
                "post_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "deleted_at": {
                  "type": "string"
                },
                "error": {
                  "type": "string"
                },
                "error_code": {
                  "type": "string"
                }
              },
              "required": [
                "success",
                "platform",
                "post_id"
              ]
            }
          },
          "no_failures": {
            "type": "boolean"
          },
          "deleted_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "failed_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "skipped_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "results",
          "no_failures",
          "deleted_count",
          "failed_count",
          "skipped_count"
        ]
      },
      "DeletePostResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "platform": {
            "type": "string"
          },
          "post_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "deleted_at": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "error_code": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "platform",
          "post_id"
        ]
      },
      "GenerateContentResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "message",
          "platforms"
        ]
      },
      "AnalyzeStartedResponse": {
        "type": "object",
        "properties": {
          "started": {
            "type": "boolean"
          },
          "persona_id": {
            "type": "string"
          }
        },
        "required": [
          "started",
          "persona_id"
        ]
      },
      "RetryContentResponse": {
        "type": "object",
        "properties": {
          "retried": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "succeeded": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "still_failing": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rate_limited": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "retried",
          "succeeded",
          "still_failing",
          "rate_limited"
        ]
      },
      "TestWebhookResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "delivery_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "response_status": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "response_body": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "success",
          "delivery_id",
          "response_status",
          "response_body"
        ]
      },
      "RotateSecretResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "secret": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "secret"
        ]
      },
      "CreateApiKeyResponse": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "api_key": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "key_prefix": {
                "type": "string"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "last_used_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "revoked_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "created_at": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name",
              "key_prefix",
              "scopes",
              "last_used_at",
              "revoked_at",
              "created_at"
            ]
          }
        },
        "required": [
          "key",
          "api_key"
        ]
      },
      "BillingPortalResponse": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          }
        },
        "required": [
          "url"
        ]
      },
      "ConnectStartResponse": {
        "type": "object",
        "properties": {
          "auth_url": {
            "type": "string"
          },
          "state": {
            "type": "string"
          }
        },
        "required": [
          "auth_url",
          "state"
        ]
      },
      "CreditBalance": {
        "type": "object",
        "properties": {
          "balance": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "packs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "credits": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                "price_usd": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "credits",
                "price_usd"
              ]
            }
          },
          "purchase_endpoint": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "balance"
        ]
      },
      "CreditPurchaseResult": {
        "type": "object",
        "properties": {
          "credits_added": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "new_balance": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "pack": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "credits": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "price_usd": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "credits",
              "price_usd"
            ]
          }
        },
        "required": [
          "credits_added",
          "new_balance",
          "pack"
        ]
      },
      "Boost": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "launch_id": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "post_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "objective": {
            "type": "string"
          },
          "daily_budget_cents": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "duration_days": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "meta_ad_account_id": {
            "type": "string"
          },
          "meta_campaign_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "meta_adset_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "meta_ad_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "impressions": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "clicks": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "reach": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "link_clicks": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "total_spend_cents": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "failure_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "stop_rules": {
            "$ref": "#/components/schemas/BoostStopRules"
          },
          "stop_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "activated_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "ended_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_synced_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "launch_id",
          "platform",
          "post_id",
          "status",
          "objective",
          "daily_budget_cents",
          "duration_days",
          "meta_ad_account_id",
          "meta_campaign_id",
          "meta_adset_id",
          "meta_ad_id",
          "impressions",
          "clicks",
          "reach",
          "total_spend_cents",
          "failure_reason",
          "created_at",
          "updated_at",
          "activated_at",
          "ended_at",
          "last_synced_at"
        ]
      },
      "BatchLaunchAnalyticsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "launch_id": {
                  "type": "string"
                },
                "launch_name": {
                  "type": "string"
                },
                "launch_status": {
                  "type": "string"
                },
                "summary": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "successful": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "failed": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "pending": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    }
                  },
                  "required": [
                    "total",
                    "successful",
                    "failed",
                    "pending"
                  ]
                },
                "platforms": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "platform": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string"
                      },
                      "post_url": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "post_id": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "posted_at": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "cache_status": {
                        "type": "string"
                      },
                      "is_deleted": {
                        "type": "boolean"
                      },
                      "deleted_detected_at": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "deletion_reason": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "metrics": {
                        "type": [
                          "object",
                          "null"
                        ],
                        "properties": {
                          "tracked_clicks": {
                            "description": "clicks on the post's tracked link (launches created with track_links)",
                            "type": "integer",
                            "minimum": -9007199254740991,
                            "maximum": 9007199254740991
                          }
                        },
                        "additionalProperties": {}
                      }
                    },
                    "required": [
                      "platform",
                      "status",
                      "post_url",
                      "post_id",
                      "posted_at",
                      "metrics"
                    ]
                  }
                }
              },
              "required": [
                "launch_id",
                "launch_name",
                "launch_status",
                "summary",
                "platforms"
              ]
            }
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              },
              "required": [
                "id",
                "error"
              ]
            }
          }
        },
        "required": [
          "data",
          "errors"
        ]
      },
      "LaunchComments": {
        "type": "object",
        "properties": {
          "launch_id": {
            "type": "string"
          },
          "posts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LaunchCommentsPost"
            }
          }
        },
        "required": [
          "launch_id",
          "posts"
        ]
      },
      "CommentReply": {
        "type": "object",
        "properties": {
          "reply_id": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "reply_id"
        ]
      },
      "CommentModeration": {
        "type": "object",
        "properties": {
          "comment_id": {
            "type": "string"
          },
          "hidden": {
            "type": "boolean"
          }
        },
        "required": [
          "comment_id",
          "hidden"
        ]
      },
      "CommentDeletion": {
        "type": "object",
        "properties": {
          "comment_id": {
            "type": "string"
          },
          "deleted": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "comment_id",
          "deleted"
        ]
      },
      "AutopilotConfig": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "mode": {
            "type": "string",
            "enum": [
              "review",
              "auto"
            ]
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "formats": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "persona_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "posting_times": {
            "type": "object",
            "properties": {
              "times": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                }
              }
            },
            "required": [
              "times",
              "days"
            ]
          },
          "run_hour": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "timezone": {
            "type": "string"
          },
          "product_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "product_image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "product_brief": {
            "type": [
              "string",
              "null"
            ]
          },
          "content_pillars": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "directives": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "min_queue": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "max_posts_per_day": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "track_links": {
            "type": "boolean"
          },
          "reuse_media": {
            "type": "boolean"
          },
          "media_source": {
            "type": "string"
          },
          "platform_settings": {
            "$ref": "#/components/schemas/AutopilotPlatformSettings"
          },
          "paused": {
            "type": "boolean"
          },
          "pause_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "enabled",
          "mode",
          "platforms",
          "formats",
          "persona_id",
          "posting_times",
          "run_hour",
          "timezone",
          "product_url",
          "product_brief",
          "content_pillars",
          "directives",
          "min_queue",
          "max_posts_per_day",
          "track_links",
          "reuse_media",
          "platform_settings",
          "paused",
          "pause_reason",
          "created_at",
          "updated_at"
        ]
      },
      "AutopilotStatus": {
        "type": "object",
        "properties": {
          "configured": {
            "type": "boolean"
          },
          "config": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "mode": {
                "type": "string",
                "enum": [
                  "review",
                  "auto"
                ]
              },
              "platforms": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "formats": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "persona_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "posting_times": {
                "type": "object",
                "properties": {
                  "times": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "days": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    }
                  }
                },
                "required": [
                  "times",
                  "days"
                ]
              },
              "run_hour": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "timezone": {
                "type": "string"
              },
              "product_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "product_image_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "product_brief": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "content_pillars": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "directives": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                }
              },
              "min_queue": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "max_posts_per_day": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "track_links": {
                "type": "boolean"
              },
              "reuse_media": {
                "type": "boolean"
              },
              "media_source": {
                "type": "string"
              },
              "platform_settings": {
                "$ref": "#/components/schemas/AutopilotPlatformSettings"
              },
              "paused": {
                "type": "boolean"
              },
              "pause_reason": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "created_at": {
                "type": "string"
              },
              "updated_at": {
                "type": "string"
              }
            },
            "required": [
              "enabled",
              "mode",
              "platforms",
              "formats",
              "persona_id",
              "posting_times",
              "run_hour",
              "timezone",
              "product_url",
              "product_brief",
              "content_pillars",
              "directives",
              "min_queue",
              "max_posts_per_day",
              "track_links",
              "reuse_media",
              "platform_settings",
              "paused",
              "pause_reason",
              "created_at",
              "updated_at"
            ]
          },
          "queued_ideas": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "pending_review": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "configured",
          "config",
          "queued_ideas",
          "pending_review"
        ]
      },
      "AutopilotReviewItem": {
        "type": "object",
        "properties": {
          "launch_id": {
            "type": "string"
          },
          "hook": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "content": {
            "type": [
              "string",
              "null"
            ]
          },
          "reddit_title": {
            "type": [
              "string",
              "null"
            ]
          },
          "scheduled_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "media_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "media_failed": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "launch_id",
          "hook",
          "platform",
          "format",
          "content",
          "reddit_title",
          "scheduled_date",
          "media_count",
          "media_failed",
          "created_at"
        ]
      },
      "AutopilotApproveResult": {
        "type": "object",
        "properties": {
          "launch_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "scheduled_date": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "launch_id",
          "status",
          "scheduled_date"
        ]
      },
      "AutopilotRejectResult": {
        "type": "object",
        "properties": {
          "launch_id": {
            "type": "string"
          },
          "rejected": {
            "type": "boolean"
          }
        },
        "required": [
          "launch_id",
          "rejected"
        ]
      },
      "AutopilotRunQueued": {
        "type": "object",
        "properties": {
          "queued": {
            "type": "boolean"
          },
          "run_date": {
            "type": "string"
          }
        },
        "required": [
          "queued",
          "run_date"
        ]
      },
      "AutopilotRun": {
        "type": "object",
        "properties": {
          "run_date": {
            "type": "string"
          },
          "step": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "stats": {},
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "started_at": {
            "type": "string"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "run_date",
          "step",
          "status",
          "stats",
          "error",
          "started_at",
          "completed_at"
        ]
      },
      "FinalizePersonaResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "analysis_limit": {
            "type": "object",
            "properties": {
              "used": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "limit": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "remaining": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "used",
              "limit",
              "remaining"
            ]
          }
        },
        "required": [
          "success",
          "analysis_limit"
        ]
      },
      "DiscardPersonaResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        },
        "required": [
          "success"
        ]
      }
    }
  }
}