{ "openapi": "3.1.0", "info": { "title": "dropspace API", "version": "1.29.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": "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": "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": "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": "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": "string", "default": "50" } }, { "name": "status", "in": "query", "required": false, "description": "filter by launch status (draft, manual, trigger, scheduled, 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" }, "scheduled_date": { "type": "string", "format": "date-time", "description": "schedule for future (≥ 15 min from now)" }, "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. published content ends with a \"posted from dropspace user\" attribution line (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:\" / \"tiktok:\" / \"youtube:\" / \"twitter:\" / \"reddit:\" (the account's entity_id from GET /connections); LinkedIn uses \"linkedin:personal\" or \"linkedin:organization:\"; Facebook uses \"facebook:page:\". 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" }, "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**" }, "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\": \"\" }`; `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`. 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). mutually exclusive with custom_content" }, "custom_content": { "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\": \"\" }`. **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:\"].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", "format": "date-time", "description": "schedule for future (≥ 15 min from now), null to unschedule" }, "status": { "type": "string", "enum": [ "draft", "manual", "trigger", "scheduled", "cancelled" ], "description": "update launch status" }, "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", "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. 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:\" / \"tiktok:\" / \"youtube:\" / \"twitter:\" / \"reddit:\" (the account's entity_id from GET /connections); LinkedIn uses \"linkedin:personal\" or \"linkedin:organization:\"; Facebook uses \"facebook:page:\". 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" }, "dropspace_platforms": { "type": "array", "items": { "type": "string" }, "description": "post via dropspace official accounts. published content ends with a \"posted from dropspace user\" attribution line (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\"\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, 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\": \"\" }` 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\": \"\"` 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" } ], "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\": \"\" }` 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, "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 are fetched live from platform APIs when stale (older than 5 minutes). calling this endpoint triggers a refresh automatically.\n\nfetched_at is the most recent timestamp when metrics were collected. next_refresh_at indicates when calling again could yield fresh data (fetched_at + 5 min).\n\ncache_status per platform: fresh (< 5 min old, from cache), refreshed (fetched from platform API), 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, comments, shares), Instagram (views, engagement, saved, likes, comments, shares), Reddit (score, upvotes, upvoteRatio, comments), TikTok (views, likes, comments, shares)\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." } }, "/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": "string" } } ], "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 - currently instagram and tiktok), 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 is the only platform returning comment content today. instagram comments arrive once an instagram permission upgrade clears review; 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/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" } } ], "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 (cached briefly), and 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\ncurrent.captured_at timestamps the reading actually returned: on a live read it is now, and if the platform call fails 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." } }, "/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)." } }, "/reddit/engagement/config": { "get": { "tags": [ "reddit" ], "summary": "read the account's engagement settings. engagement = commenting on OTHER people's threads to EARN standing (the 90 side of reddit's 90:10 norm) so later fan-out posts clear the publish gate. ships disabled; `gate_passed` (14-day account age + 50 karma) is required before discovery drafts anything.", "operationId": "getEngagementConfig", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/EngagementConfig" } }, "required": [ "data" ] }, "example": { "data": { "enabled": false, "max_comments_per_day": 5, "max_comments_per_sub_per_day": 2, "min_gap_minutes": 20, "gate_passed": true, "account_username": "your_reddit_handle", "account_total_karma": 1240, "persona_id": null, "auto_approve": false } } } } } } }, "put": { "tags": [ "reddit" ], "summary": "enable/disable engagement and tune caps. the caps are STRUCTURAL RAILS: an agent may only tighten them (fewer per day, longer gaps). a request above the ceiling (5/day, 2/sub/day, 20-min gap) is clamped, not obeyed. this is deliberate: the rails prevent the account bans that unreviewed promo causes, and they are not agent-overridable.", "operationId": "updateEngagementConfig", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/EngagementConfig" } }, "required": [ "data" ] }, "example": { "data": { "enabled": true, "max_comments_per_day": 5, "max_comments_per_sub_per_day": 2, "min_gap_minutes": 20, "gate_passed": true, "account_username": "your_reddit_handle", "account_total_karma": 1240, "persona_id": null, "auto_approve": false } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "turn engagement on/off for this account" }, "max_comments_per_day": { "type": "string", "description": "clamped to 5" }, "max_comments_per_sub_per_day": { "type": "string", "description": "clamped to 2" }, "min_gap_minutes": { "type": "string", "description": "floored at 20" }, "persona_id": { "type": "string", "description": "which persona voices the comments; null = auto (latest)" }, "auto_approve": { "type": "boolean", "description": "post drafted comments automatically instead of holding them in the review queue - every auto-approval still runs the same rails (daily/per-sub caps, pacing, kill switch)" } }, "required": [ "enabled" ] } } } } } }, "/reddit/engagement/discover": { "post": { "tags": [ "reddit" ], "summary": "draft comments for the account's active subreddits on demand (the agent-triggered equivalent of the nightly sweep). fills the review queue; posts NOTHING. `skipped` names why nothing ran: kill_switch (globally off), not_enabled (enable via PUT config), or gate_not_passed (account too new / low karma).", "operationId": "discoverEngagement", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/EngagementSweepResult" } }, "required": [ "data" ] }, "example": { "data": { "drafted": 3, "skipped": null } } } } } } } }, "/reddit/engagement/comments": { "get": { "tags": [ "reddit" ], "summary": "list drafted/posted comments. `?status=pending` (default) is the review queue awaiting approve/reject; `?status=history` is everything already acted on (posted/verified/removed/rejected/expired). `target` carries the thread context on thread replies, null on own-post first comments.", "operationId": "listEngagementComments", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EngagementComment" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "uuid", "comment_kind": "thread_reply", "subreddit": "webdev", "body": "we hit the same thing, windowing beat memoization for us too.", "status": "pending_review", "scheduled_for": null, "comment_permalink": null, "comment_score": null, "error_message": null, "created_at": "ISO 8601", "target": { "subreddit": "webdev", "thread_title": "how do you virtualize a huge table?", "thread_url": "https://reddit.com/r/webdev/comments/...", "thread_author": "someone", "relevance_score": 82 } } ] } } } } } } }, "/reddit/engagement/comments/{id}/approve": { "post": { "tags": [ "reddit" ], "summary": "approve a drafted comment: this posts it. the human review step is lifted, the RAILS are not: approval computes a pacing slot against the per-day and per-sub caps and the min-gap and returns 429 when any is hit, so an agent cannot post faster or more than the structural limits allow. optional body `{ \"body\": \"\" }` edits the draft first.", "operationId": "approveEngagementComment", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/EngagementApproveResult" } }, "required": [ "data" ] }, "example": { "data": { "scheduled_for": "ISO 8601" } } } } }, "400": { "description": "SERVER_002: engagement is disabled (kill switch)", "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: no pending draft with that 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" ] } } } }, "429": { "description": "RATE_001: daily/per-sub cap or pacing gap 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" } ] } }, "/reddit/engagement/comments/{id}/reject": { "post": { "tags": [ "reddit" ], "summary": "discard a drafted comment without posting.", "operationId": "rejectEngagementComment", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/EngagementRejectResult" } }, "required": [ "data" ] }, "example": { "data": { "id": "uuid", "status": "rejected" } } } } }, "404": { "description": "LAUNCH_001: no pending draft with that 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": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/reddit/engagement/subreddits": { "post": { "tags": [ "reddit" ], "summary": "activate a subreddit as an engagement candidate: the seed that lets a fresh account draft its first comments. `discover` only drafts in subreddits the account is active in, so a new account (no standing, no reddit launches yet) has nowhere to start. run `POST /reddit/subreddits/suggest`, pick the relevant ICP subs, activate them here, then `discover`. you choose the communities; the machine only sustains engagement within them.", "operationId": "activateEngagementSubreddit", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/EngagementSubreddit" } }, "required": [ "data" ] }, "example": { "data": { "subreddit": "webdev", "engagement_enabled": true } } } } }, "400": { "description": "SERVER_002: subreddit missing or invalid", "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": { "subreddit": { "type": "string", "description": "community name, no r/ prefix" } }, "required": [ "subreddit" ] } } } } } }, "/reddit/engagement/subreddits/{name}": { "delete": { "tags": [ "reddit" ], "summary": "stop drafting comments for a subreddit. earned standing (tier, karma) is kept, so re-activating later resumes from where it left off.", "operationId": "deactivateEngagementSubreddit", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/EngagementSubreddit" } }, "required": [ "data" ] }, "example": { "data": { "subreddit": "webdev", "engagement_enabled": false } } } } } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "name" } ] } }, "/reddit/engagement/standing": { "get": { "tags": [ "reddit" ], "summary": "the standing the account has EARNED per subreddit: `tier` (none → seedling → active → established), comments posted, karma earned, and any active pause (a removal pauses a subreddit for 7 days). this is what makes a subreddit go green in discovery and lets its fan-out posts clear the 90:10 gate.", "operationId": "getEngagementStanding", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubredditStanding" } } }, "required": [ "data" ] }, "example": { "data": [ { "subreddit": "webdev", "tier": "active", "comments_posted": 14, "comments_removed": 0, "karma_earned": 63, "paused_until": null, "pause_reason": null, "last_activity_at": "ISO 8601" } ] } } } } } } }, "/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": "string", "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" }, "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": "string", "description": "custom writing samples" }, "twitter_samples": { "type": "string", "description": "Twitter writing samples" }, "reddit_samples": { "type": "string", "description": "Reddit writing samples" }, "facebook_samples": { "type": "string", "description": "Facebook writing samples" }, "instagram_samples": { "type": "string", "description": "Instagram writing samples" }, "tiktok_samples": { "type": "string", "description": "TikTok writing samples" }, "linkedin_samples": { "type": "string", "description": "LinkedIn writing samples" } } } } } } }, "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" }, "include_custom_samples": { "type": "boolean", "description": "include custom samples in 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": "string", "description": "platforms to post on - each needs a connected account. valid: facebook, linkedin, twitter, reddit, instagram, tiktok, youtube" }, "formats": { "type": "string", "description": "\"text\", \"visual\" (AI image slides), and/or \"video\"", "default": "[\"text\"]" }, "persona_id": { "type": "string", "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": "string", "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", "description": "product link included in posts" }, "product_brief": { "type": "string", "description": "what you're building, who it's for" }, "content_pillars": { "type": "string", "description": "themes the engine rotates across" }, "directives": { "type": "string", "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": "string", "description": "ideas to keep queued", "default": "7" }, "max_posts_per_day": { "type": "string", "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" }, "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": "string", "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": "steps that already completed today are skipped, so a manual run tops up rather than double-posts" } }, "/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": "string", "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": "string", "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": "string", "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)" } }, "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" } }, "/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, "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": "string", "default": "50" } } ], "description": "connecting a new platform happens via the dashboard OAuth flow; use DELETE to disconnect" } }, "/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" } }, "/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": "reddit", "connected": false }, { "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" } ] } }, "/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" }, "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), \"connection.expired\" (a connected account's token was invalidated and needs reauth)\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\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": "string", "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" } } ] } }, "/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\nif a launch creation fails after credit deduction, the credit is refunded automatically\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": "_", "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, "total_spend_cents": 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": "string", "description": "daily ad budget in cents ($1 - $100 per day). billed by meta to the user's ad account." }, "duration_days": { "type": "string", "description": "boost duration in days" }, "objective": { "type": "string", "enum": [ "engagement" ], "description": "campaign objective (phase 1: engagement only)", "default": "engagement" }, "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" ] }, "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" ] } }, "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" ] }, "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" ] }, "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" } }, "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" ] }, "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" ], "propertyNames": { "type": "string" }, "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" ] }, "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": {} }, "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" ] }, "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" }, "expires_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "platform", "entity_id", "account_info", "account_type", "is_active", "expires_at", "created_at", "updated_at" ] }, "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" ] }, "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" ] }, "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 }, "total_spend_cents": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failure_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" ], "propertyNames": { "type": "string" }, "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" ] }, "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_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" }, "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_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" }, "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" ] } } } }