{ "openapi": "3.1.0", "info": { "title": "dropspace API", "version": "1.4.0", "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. 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": "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": "media", "description": "generate AI images and videos for your launches." }, { "name": "connections", "description": "view your OAuth platform connections (read-only)." }, { "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." } ], "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": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "correlation id for support tickets / Sentry; also returned in X-Request-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" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "launch title" }, "product_description": { "type": "string", "description": "product description - required unless 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 for context)" }, "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" }, "user_platform_accounts": { "type": "object", "description": "map of platform key → token_id (UUID). most platforms use simple keys: \"twitter\", \"reddit\", \"instagram\", \"tiktok\", \"youtube\". LinkedIn uses \"linkedin:personal\" for personal profiles or \"linkedin:organization:\" for company pages. Facebook uses \"facebook:page:\". multiple keys allowed (e.g. post to personal + org simultaneously)" }, "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). 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). `send` was renamed from `publish` 2026-05-07; legacy keys with `publish` in their scope array continue to work via SCOPE_ALIASES." }, "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\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 (`send` was renamed from `publish` 2026-05-07; legacy `publish` still works via SCOPE_ALIASES)\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 simple keys: \"twitter\", \"reddit\", \"instagram\", \"tiktok\", \"youtube\". LinkedIn uses \"linkedin:personal\" for personal profiles or \"linkedin:organization:\" for company pages. Facebook uses \"facebook:page:\". multiple keys allowed (e.g. post to personal + org simultaneously)" }, "dropspace_platforms": { "type": "array", "items": { "type": "string" }, "description": "post via dropspace official accounts" }, "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", "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" } } } } } }, "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}/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/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). legacy keys with `delete` in their scope array continue to work via SCOPE_ALIASES (`delete` → `write`)\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). legacy keys with `delete` in their scope array continue to work via SCOPE_ALIASES (`delete` → `write`)\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" } }, "/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, youtube_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" }, "youtube_samples": { "type": "string", "description": "YouTube 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" } }, "/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" ] }, "example": { "data": { "configured": true, "config": { "enabled": true, "mode": "review", "platforms": [ "twitter", "linkedin" ], "formats": [ "text", "visual" ], "persona_id": "uuid | null", "posting_times": { "times": [ "09:30", "17:30" ], "days": [ 1, 2, 3, 4, 5 ] }, "run_hour": 2, "timezone": "America/New_York", "product_url": "string | null", "product_brief": "string | null", "content_pillars": [ "string" ], "min_queue": 7, "max_posts_per_day": 4, "paused": false, "pause_reason": null, "created_at": "ISO 8601", "updated_at": "ISO 8601" }, "queued_ideas": 9, "pending_review": 3 } } } } } }, "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)", "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" }, "min_queue": { "type": "string", "description": "ideas to keep queued", "default": "7" }, "max_posts_per_day": { "type": "string", "description": "daily posting cap", "default": "4" } } } } } }, "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" } } ] } }, "/media/generate": { "post": { "tags": [ "media" ], "summary": "submit an image or video generation job", "operationId": "generateMedia", "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "success", "content": { "application/json": { "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": "required for script_video: \"instagram\", \"tiktok\", or \"youtube\"" }, "prompt": { "type": "string", "description": "generation prompt (required for script_video)" }, "product_description": { "type": "string", "description": "product context" }, "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" }, "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', 'tiktok', or 'youtube' 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": "connections are managed via the dashboard OAuth flow - this endpoint is read-only" } }, "/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 (default: read, write, generate, send). available: read, write, generate, send, admin. legacy values `publish` (now `send`) and `delete` (now `write`) still authenticate via SCOPE_ALIASES for grandfathered keys." } }, "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" } ] } } } } } }, "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 } } } } }, "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)\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\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" } } } } }, "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" } }, "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." } } }, "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" ] } } }, "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" ], "additionalProperties": false, "id": "UsageLimitEntry" }, "UsageLimit": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string", "const": "unlimited" } ], "id": "UsageLimit" }, "UsageLimitOnly": { "type": "object", "properties": { "limit": { "$ref": "#/components/schemas/UsageLimit" } }, "required": [ "limit" ], "additionalProperties": false, "id": "UsageLimitOnly" }, "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" ], "additionalProperties": false } }, "error_message": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "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", "platform_contents", "media_assets", "error_message", "started_at", "completed_at", "created_at", "updated_at" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false } } }, "required": [ "launch_id", "launch_status", "posting_logs" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false } } }, "required": [ "launch_id", "launch_name", "launch_status", "summary", "fetched_at", "next_refresh_at", "platforms" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" } }, "required": [ "id", "url", "events", "active", "created_at", "updated_at" ], "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "webhook_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string" }, "attempts": { "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" ] }, "created_at": { "type": "string" } }, "required": [ "id", "webhook_id", "event_type", "status", "attempts", "response_status", "response_body", "delivered_at", "created_at" ], "additionalProperties": false }, "DropspaceStatus": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "connected": { "type": "boolean" }, "account_name": { "type": "string" } }, "required": [ "platform", "connected" ], "additionalProperties": false } }, "connected_platforms": { "type": "array", "items": { "type": "string" } }, "timestamp": { "type": "string" } }, "required": [ "platforms", "connected_platforms", "timestamp" ], "additionalProperties": false }, "UsageData": { "type": "object", "properties": { "plan": { "type": "string" }, "billing_period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false } }, "required": [ "plan", "billing_period", "limits", "features" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "MessageResponse": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false }, "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" ], "additionalProperties": false } }, "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" ], "additionalProperties": false }, "GenerateContentResponse": { "type": "object", "properties": { "message": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "platforms" ], "additionalProperties": false }, "AnalyzeStartedResponse": { "type": "object", "properties": { "started": { "type": "boolean" }, "persona_id": { "type": "string" } }, "required": [ "started", "persona_id" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "RotateSecretResponse": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "secret" ], "additionalProperties": false }, "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" ], "additionalProperties": false } }, "required": [ "key", "api_key" ], "additionalProperties": false }, "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" ], "additionalProperties": false } }, "purchase_endpoint": { "type": "string" }, "message": { "type": "string" } }, "required": [ "balance" ], "additionalProperties": false }, "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" ], "additionalProperties": false } }, "required": [ "credits_added", "new_balance", "pack" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" ], "additionalProperties": false } } }, "required": [ "launch_id", "launch_name", "launch_status", "summary", "platforms" ], "additionalProperties": false } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "id", "error" ], "additionalProperties": false } } }, "required": [ "data", "errors" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" } }, "min_queue": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_posts_per_day": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "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", "min_queue", "max_posts_per_day", "paused", "pause_reason", "created_at", "updated_at" ], "additionalProperties": false }, "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" ], "additionalProperties": false }, "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" } }, "min_queue": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_posts_per_day": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "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", "min_queue", "max_posts_per_day", "paused", "pause_reason", "created_at", "updated_at" ], "additionalProperties": false }, "queued_ideas": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pending_review": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "configured", "config", "queued_ideas", "pending_review" ], "additionalProperties": false }, "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 }, "created_at": { "type": "string" } }, "required": [ "launch_id", "hook", "platform", "format", "content", "reddit_title", "scheduled_date", "media_count", "created_at" ], "additionalProperties": false }, "AutopilotApproveResult": { "type": "object", "properties": { "launch_id": { "type": "string" }, "status": { "type": "string" }, "scheduled_date": { "type": [ "string", "null" ] } }, "required": [ "launch_id", "status", "scheduled_date" ], "additionalProperties": false }, "AutopilotRejectResult": { "type": "object", "properties": { "launch_id": { "type": "string" }, "rejected": { "type": "boolean" } }, "required": [ "launch_id", "rejected" ], "additionalProperties": false }, "AutopilotRunQueued": { "type": "object", "properties": { "queued": { "type": "boolean" }, "run_date": { "type": "string" } }, "required": [ "queued", "run_date" ], "additionalProperties": false }, "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" ], "additionalProperties": false } } } }