{ "openapi": "3.1.0", "info": { "title": "PostQuickAI API", "version": "1.0.0", "description": "REST API for PostQuickAI — generate content, schedule posts, manage social accounts, and run analytics across 8+ platforms. Bearer token auth (pq_live_*). Used directly or via the @postquickai/mcp MCP server for agent integration.", "license": { "name": "PostQuickAI Terms", "url": "https://www.postquick.ai/terms" }, "contact": { "name": "PostQuickAI", "url": "https://www.postquick.ai/developers" } }, "servers": [ { "url": "https://www.postquick.ai/api", "description": "Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "PostQuickAI API key in the format `pq_live_...`. Requires the API add-on." } }, "schemas": {}, "parameters": {} }, "paths": { "/v1/webhooks": { "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "description": "List your registered webhook endpoints. Optionally filter by `app_id`. The plaintext signing secret is never returned — only `secret_preview` for identification.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Filter to endpoints for one content group." }, "required": false, "description": "Filter to endpoints for one content group.", "name": "app_id", "in": "query" } ], "responses": { "200": { "description": "Array of webhook endpoints.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed events (e.g. [\"post.partial\"]) or [\"*\"] for all." }, "active": { "type": "boolean" }, "secret_preview": { "type": "string", "description": "First 8 chars of the signing secret. Useful for identifying which secret an endpoint uses without exposing it." }, "consecutive_failures": { "type": "integer", "description": "Count of consecutive failed deliveries. Auto-disables the endpoint at 50; resets to 0 on the first 2xx response." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "url", "events", "active", "secret_preview", "consecutive_failures", "created_at", "updated_at" ], "description": "A registered webhook endpoint." } } }, "required": [ "endpoints" ] } }, "required": [ "success", "data" ] } } } } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "description": "Register a URL to receive publish-event webhooks. Returns the plaintext signing secret EXACTLY ONCE — store it immediately. Use it to verify the X-PostQuickAI-Signature header on incoming deliveries. Lost secrets can be replaced via /rotate-secret but not retrieved.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "app_id": { "type": "string", "format": "uuid", "description": "Content group to attach the endpoint to." }, "url": { "type": "string", "format": "uri", "description": "Publicly reachable HTTPS URL. Loopback / private IPs are rejected." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "post.posted", "post.partial", "post.failed", "video.posted", "video.partial", "video.failed", "story.posted", "story.partial", "story.failed", "*" ], "description": "Webhook event name. Subscribe to specific events or use `*` for all. Nine concrete events: post/video/story × posted/partial/failed." }, "description": "Events to subscribe to. Default is [\"*\"] (all events). Valid event names: post.{posted,partial,failed}, video.{posted,partial,failed}, story.{posted,partial,failed}." } }, "required": [ "app_id", "url" ] } } } }, "responses": { "201": { "description": "Endpoint created. Response includes the plaintext signing secret.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "endpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed events (e.g. [\"post.partial\"]) or [\"*\"] for all." }, "active": { "type": "boolean" }, "secret_preview": { "type": "string", "description": "First 8 chars of the signing secret. Useful for identifying which secret an endpoint uses without exposing it." }, "consecutive_failures": { "type": "integer", "description": "Count of consecutive failed deliveries. Auto-disables the endpoint at 50; resets to 0 on the first 2xx response." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "url", "events", "active", "secret_preview", "consecutive_failures", "created_at", "updated_at" ], "description": "A registered webhook endpoint." }, "secret": { "type": "string", "description": "Plaintext signing secret. Returned exactly once." }, "secret_notice": { "type": "string" } }, "required": [ "endpoint", "secret", "secret_notice" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/videos": { "get": { "operationId": "listVideos", "summary": "List videos", "description": "List video posts (Reels) for a content group. Filter by status if you only need a subset (e.g. status=scheduled).", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group to filter by (required)." }, "required": true, "description": "Content group to filter by (required).", "name": "contentGroupId", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "required": false, "description": "Filter by lifecycle status.", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Array of video posts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "title", "description", "status", "video_url", "thumbnail_url", "platforms", "posted_platforms", "scheduled_for", "posted_at", "error_message", "platform_errors" ], "description": "A video post record" } } }, "required": [ "videos" ] } }, "required": [ "success", "data" ] } } } } } }, "post": { "operationId": "createVideo", "summary": "Create a video (Reel) from a URL", "description": "Create a video post (Reel) draft from a publicly accessible video URL — the canonical way to post your OWN uploaded video to any platform (TikTok, YouTube, Instagram Reels, Facebook Reels, X, Threads, LinkedIn). Charges one video generation against your monthly quota. Then call POST /v1/videos/{videoId}/schedule or /publish.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contentGroupId": { "type": "string", "description": "Content group (app) that owns this video." }, "videoUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of the video, e.g. the videoUrl returned by POST /v1/videos/upload. Platform APIs pull the media from this URL during publishing." }, "title": { "type": "string", "description": "Title (used by YouTube; optional elsewhere)." }, "description": { "type": "string", "description": "Caption / description." }, "thumbnailUrl": { "type": "string", "format": "uri", "description": "Optional thumbnail image URL." }, "duration": { "type": "integer", "description": "Duration in seconds." }, "resolution": { "type": "string", "description": "e.g. \"1080x1920\"." }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" }, "description": "Target platforms. Can also be set later via publish/schedule." }, "visibility": { "type": "string", "description": "Platform visibility, e.g. \"public\". Default \"public\"." }, "tags": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "facebookTarget": { "type": "object", "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "linkedinTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "tiktokSettings": { "type": "object", "additionalProperties": {} } }, "required": [ "contentGroupId", "videoUrl" ] } } } }, "responses": { "201": { "description": "Video draft created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "title", "description", "status", "video_url", "thumbnail_url", "platforms", "posted_platforms", "scheduled_for", "posted_at", "error_message", "platform_errors" ], "description": "A video post record" } }, "required": [ "video" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "summary": "Usage & limits", "description": "Returns current monthly usage vs. plan limits for text generation, image generation, video credits, and content groups.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Usage snapshot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "plan": { "type": "string" }, "monthlyTextGenerations": { "type": "object", "properties": { "used": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "used", "limit" ] }, "monthlyImageGenerations": { "type": "object", "properties": { "used": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "used", "limit" ] }, "videoCredits": { "type": "object", "properties": { "remaining": { "type": "number" } }, "required": [ "remaining" ] }, "contentGroups": { "type": "object", "properties": { "used": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "used", "limit" ] } }, "required": [ "plan", "monthlyTextGenerations", "monthlyImageGenerations", "videoCredits", "contentGroups" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/stories": { "get": { "operationId": "listStories", "summary": "List stories", "description": "List stories for a content group. Filter by status if you only need a subset (e.g. status=scheduled).", "tags": [ "Stories" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group to filter by (required)." }, "required": true, "description": "Content group to filter by (required).", "name": "contentGroupId", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "required": false, "description": "Filter by lifecycle status.", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Array of stories.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "stories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "story_type": { "type": "string", "enum": [ "image", "video" ], "description": "Story media type" }, "image_url": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "duration": { "type": [ "number", "null" ] }, "aspect_ratio": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "platforms": { "type": "array", "items": { "type": "string" } }, "posted_platforms": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "source_post_id": { "type": [ "string", "null" ] }, "source_video_id": { "type": [ "string", "null" ] }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "story_type", "image_url", "video_url", "thumbnail_url", "duration", "aspect_ratio", "caption", "platforms", "posted_platforms", "status", "scheduled_for", "posted_at", "expires_at", "error_message", "platform_errors", "platform_post_ids", "source_post_id", "source_video_id", "facebook_target" ], "description": "A Story record — short-lived (24h) content for Instagram, Facebook, or TikTok" } } }, "required": [ "stories" ] } }, "required": [ "success", "data" ] } } } } } }, "post": { "operationId": "createStory", "summary": "Create a Story", "description": "Create a Story draft from a publicly accessible media URL. Charges against the image or video generation quota (one upload = one charge). Use POST /v1/stories/{storyId}/publish or /schedule to actually post it.", "tags": [ "Stories" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contentGroupId": { "type": "string", "description": "Content group to create the story in." }, "storyType": { "type": "string", "enum": [ "image", "video" ], "description": "Story media type" }, "mediaUrl": { "type": "string", "format": "uri", "description": "Publicly accessible URL of the story media. Graph API and TikTok pull from this URL during publishing." }, "thumbnailUrl": { "type": "string", "format": "uri", "description": "Optional thumbnail for video stories." }, "caption": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "facebook", "tiktok" ], "description": "Platform that supports Stories" }, "description": "Target platforms. Can also be set later via publish/schedule." }, "duration": { "type": "integer", "maximum": 60, "description": "Video duration in seconds. Stories must be ≤60s." }, "mediaFit": { "type": "string", "enum": [ "contain", "cover", "fill" ], "description": "How non-9:16 media is fitted into the 1080x1920 story frame: contain (letterbox with black bars, default), cover (crop to fill), or fill (stretch)." } }, "required": [ "contentGroupId", "storyType", "mediaUrl" ] } } } }, "responses": { "201": { "description": "Story draft created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "story": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "story_type": { "type": "string", "enum": [ "image", "video" ], "description": "Story media type" }, "image_url": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "duration": { "type": [ "number", "null" ] }, "aspect_ratio": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "platforms": { "type": "array", "items": { "type": "string" } }, "posted_platforms": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "source_post_id": { "type": [ "string", "null" ] }, "source_video_id": { "type": [ "string", "null" ] }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "story_type", "image_url", "video_url", "thumbnail_url", "duration", "aspect_ratio", "caption", "platforms", "posted_platforms", "status", "scheduled_for", "posted_at", "expires_at", "error_message", "platform_errors", "platform_post_ids", "source_post_id", "source_video_id", "facebook_target" ], "description": "A Story record — short-lived (24h) content for Instagram, Facebook, or TikTok" } }, "required": [ "story" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/posts": { "get": { "operationId": "listPosts", "summary": "List posts", "description": "List posts filtered by content group and/or status. Use this to enumerate posts before acting on a specific one.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Filter to a single content group." }, "required": false, "description": "Filter to a single content group.", "name": "contentGroupId", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "required": false, "description": "Filter by lifecycle status.", "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Max results. Default 50." }, "required": false, "description": "Max results. Default 50.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "description": "Pagination offset." }, "required": false, "description": "Pagination offset.", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Array of posts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" } } }, "required": [ "posts" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/me": { "get": { "operationId": "getMe", "summary": "Authenticated user info", "description": "Returns the authenticated user's email, user ID, subscription plan, and API key info.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "User info.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "userId": { "type": "string" }, "userEmail": { "type": "string", "format": "email" }, "plan": { "type": "string" }, "apiKeyName": { "type": "string" } }, "required": [ "userId", "userEmail", "plan" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content-groups": { "get": { "operationId": "listContentGroups", "summary": "List content groups", "description": "Returns every content group (a.k.a. \"app\" — one per brand/project) owned by the authenticated user.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Array of content groups.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "contentGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "user_id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "user_id", "name" ], "description": "A content group (a.k.a. \"app\" — a brand/project container)" } } }, "required": [ "contentGroups" ] } }, "required": [ "success", "data" ] } } } } } }, "post": { "operationId": "createContentGroup", "summary": "Create a content group", "description": "Creates a new content group. Content groups act as containers for posts, brand instructions, and connected social accounts. Subject to the content-group limit on your plan.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The display name of the content group (e.g. \"Acme Fitness\")" }, "description": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" }, "description": "Initial list of platforms to associate with this group. Can be added later." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Content group created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "contentGroup": { "type": "object", "properties": { "id": { "type": "string" }, "user_id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "user_id", "name" ], "description": "A content group (a.k.a. \"app\" — a brand/project container)" } }, "required": [ "contentGroup" ] } }, "required": [ "success", "data" ] } } } }, "403": { "description": "Content group limit reached." } } } }, "/v1/analytics": { "get": { "operationId": "getApiAnalytics", "summary": "API analytics", "description": "Operational analytics for your own API usage: request volume, error rates, average response times, breakdowns by endpoint / status code / key, recent errors, and rate-limit meters. Read-only and scoped to the authenticated account. Accepts a pq_live_ API key or a dashboard session.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ], "description": "Analytics window. Default: 7d." }, "required": false, "description": "Analytics window. Default: 7d.", "name": "period", "in": "query" } ], "responses": { "200": { "description": "Usage analytics for the requested window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "totalRequests": { "type": "number" }, "successRate": { "type": "number" }, "avgResponseTime": { "type": "number" }, "uniqueEndpoints": { "type": "number" }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" } }, "required": [ "totalRequests", "successRate", "avgResponseTime", "uniqueEndpoints", "periodStart", "periodEnd" ] }, "requestsOverTime": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "total": { "type": "number" }, "success": { "type": "number" }, "errors": { "type": "number" } }, "required": [ "date", "total", "success", "errors" ] } }, "byEndpoint": { "type": "array", "items": { "type": "object", "properties": { "endpoint": { "type": "string" }, "count": { "type": "number" }, "avgMs": { "type": "number" }, "errorRate": { "type": "number" } }, "required": [ "endpoint", "count", "avgMs", "errorRate" ] } }, "byStatusCode": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "number" }, "count": { "type": "number" } }, "required": [ "code", "count" ] } }, "byApiKey": { "type": "array", "items": { "type": "object", "properties": { "keyId": { "type": "string" }, "name": { "type": "string" }, "count": { "type": "number" }, "lastUsed": { "type": "string" } }, "required": [ "keyId", "name", "count", "lastUsed" ] } }, "recentErrors": { "type": "array", "items": { "type": "object", "properties": { "endpoint": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "at": { "type": "string" } }, "required": [ "endpoint", "status", "message", "at" ] } }, "rateLimitStatus": { "type": "object", "properties": { "plan": { "type": "string" }, "minuteLimit": { "type": "number" }, "minuteUsed": { "type": "number" }, "dailyLimit": { "type": "number" }, "dailyUsed": { "type": "number" } }, "required": [ "plan", "minuteLimit", "minuteUsed", "dailyLimit", "dailyUsed" ] } }, "required": [ "summary", "requestsOverTime", "byEndpoint", "byStatusCode", "byApiKey", "recentErrors", "rateLimitStatus" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/accounts": { "get": { "operationId": "listAccounts", "summary": "List connected social accounts", "description": "Returns every social account (Twitter/X, Threads, Bluesky, LinkedIn, Facebook, Instagram, YouTube, TikTok) connected across all the user's content groups.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Array of connected accounts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "platform": { "type": "string" }, "account_name": { "type": [ "string", "null" ] }, "token_status": { "type": "string", "enum": [ "valid", "expired", "reconnect_required", "unknown" ], "description": "Connection-health of the social account. `valid` = token worked recently; `reconnect_required` = the platform returned an auth error; `expired` = the token's stored `expires_at` is in the past; `unknown` = no recent signal (either never validated or last validation is >14 days stale)." }, "last_validated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp of the most recent token validation (success or known failure)." }, "last_validation_error": { "type": [ "string", "null" ], "description": "Most recent auth-error message returned by the platform, if any." }, "follower_count": { "type": [ "number", "null" ], "description": "Current follower count for this account, as of `followers_fetched_at`. Null when the platform does not expose this (X v2 free tier, LinkedIn personal profiles, YouTube channels with hidden subscriber count)." }, "following_count": { "type": [ "number", "null" ], "description": "Current following count, where the platform exposes it." }, "followers_fetched_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp of the most recent follower-count snapshot." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "platform", "account_name" ], "description": "A connected social media account" } } }, "required": [ "accounts" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/webhooks/{id}": { "get": { "operationId": "getWebhookEndpoint", "summary": "Get a webhook endpoint", "description": "Fetch a single endpoint. The plaintext secret is never returned.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "endpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed events (e.g. [\"post.partial\"]) or [\"*\"] for all." }, "active": { "type": "boolean" }, "secret_preview": { "type": "string", "description": "First 8 chars of the signing secret. Useful for identifying which secret an endpoint uses without exposing it." }, "consecutive_failures": { "type": "integer", "description": "Count of consecutive failed deliveries. Auto-disables the endpoint at 50; resets to 0 on the first 2xx response." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "url", "events", "active", "secret_preview", "consecutive_failures", "created_at", "updated_at" ], "description": "A registered webhook endpoint." } }, "required": [ "endpoint" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Not found." } } }, "patch": { "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Toggle active state, change the URL, or change the subscribed events list. Re-enabling (active=true) resets the consecutive_failures counter so the endpoint gets a fresh window before auto-disable.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "post.posted", "post.partial", "post.failed", "video.posted", "video.partial", "video.failed", "story.posted", "story.partial", "story.failed", "*" ], "description": "Webhook event name. Subscribe to specific events or use `*` for all. Nine concrete events: post/video/story × posted/partial/failed." } }, "active": { "type": "boolean", "description": "Toggle active state. Setting active=true also resets consecutive_failures to 0." } }, "description": "Partial update — only provided fields are changed." } } } }, "responses": { "200": { "description": "Updated endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "endpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed events (e.g. [\"post.partial\"]) or [\"*\"] for all." }, "active": { "type": "boolean" }, "secret_preview": { "type": "string", "description": "First 8 chars of the signing secret. Useful for identifying which secret an endpoint uses without exposing it." }, "consecutive_failures": { "type": "integer", "description": "Count of consecutive failed deliveries. Auto-disables the endpoint at 50; resets to 0 on the first 2xx response." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "url", "events", "active", "secret_preview", "consecutive_failures", "created_at", "updated_at" ], "description": "A registered webhook endpoint." } }, "required": [ "endpoint" ] } }, "required": [ "success", "data" ] } } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "description": "Hard delete. Cascades to delete all delivery history for the endpoint.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "deleted", "id" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/videos/upload": { "post": { "operationId": "uploadVideo", "summary": "Upload a video", "description": "Get a video file into PostQuickAI hosted storage. The returned `videoUrl` is on a domain whitelisted by our TikTok developer app, so it can be passed straight to /v1/posts/create as `videoUrl` for TikTok / YouTube / Instagram Reels publishing without URL ownership errors.\n\nTwo modes:\n\nA) Inline base64 (MCP / LLM friendly, ≤ 25MB decoded):\n POST `{ data: base64String, contentType?, fileName? }` → get back `{ videoUrl, contentType, size }` in one call. No follow-up PUT needed.\n\nB) Signed URL (required for videos > 25MB, up to 500MB):\n 1. POST `{ contentType, size }` → get back `{ uploadUrl, videoUrl, headers }`.\n 2. PUT the raw video bytes to `uploadUrl` using the returned `headers`.\n\nLimits: video/mp4, video/webm, video/quicktime. Counts against your storage quota at request time.\n\nTypical MCP flow: call `uploadVideo` with inline base64 `data` → take the returned `videoUrl` → pass it as `videoUrl` to `createPost`.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "Raw video bytes encoded as base64 (or a full data: URL). When present, the server uploads inline and returns just `videoUrl` — no follow-up PUT required. Use this for MCP / LLM tool calls. Max 25MB decoded; for larger videos omit `data` and use the signed-URL flow instead." }, "contentType": { "type": "string", "enum": [ "video/mp4", "video/webm", "video/quicktime" ], "description": "MIME type of the video. Required for the signed-URL flow. Optional when `data` is provided (sniffed from bytes or data-URL prefix), but supplying it is the most reliable." }, "size": { "type": "integer", "exclusiveMinimum": 0, "description": "Size of the video in bytes. Required for the signed-URL flow (storage quota enforcement). Ignored when `data` is provided. Max 500MB." }, "fileName": { "type": "string", "description": "Optional original file name. Only used to derive a fallback extension." } } } } } }, "responses": { "201": { "description": "Signed upload URL issued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "uploadUrl": { "type": "string", "format": "uri", "description": "Pre-signed Supabase Storage URL — only returned in the signed-URL flow. PUT the raw video bytes here within `expiresIn` seconds. Omitted when `data` was uploaded inline." }, "videoUrl": { "type": "string", "format": "uri", "description": "Final public URL of the video. For inline uploads it is already populated; for signed-URL uploads it becomes valid once the PUT succeeds. Pass to /v1/posts/create as videoUrl." }, "method": { "type": "string", "enum": [ "PUT" ], "description": "HTTP method to use for the upload. Only present in the signed-URL flow." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers that must be sent on the PUT request. Only present in the signed-URL flow." }, "expiresIn": { "type": "integer", "description": "Seconds until the uploadUrl expires (default 7200 / 2 hours). Only present in the signed-URL flow." }, "contentType": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "videoUrl", "contentType", "size" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Invalid request (missing/invalid contentType, size, or oversized)." }, "403": { "description": "Storage limit exceeded." } } } }, "/v1/videos/generate": { "post": { "operationId": "generateVideo", "summary": "Generate a video", "description": "Start an async video generation job. Poll with getVideoStatus. Returns a video post record with status=\"generating\".", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contentGroupId": { "type": "string" }, "prompt": { "type": "string", "description": "Description of the video content to generate" }, "model": { "type": "string", "description": "Video model override (e.g. \"veo-3\", \"sora-2\")" }, "aspect_ratio": { "type": "string", "enum": [ "9:16", "16:9", "1:1" ] } }, "required": [ "contentGroupId", "prompt" ] } } } }, "responses": { "201": { "description": "Video generation started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "title", "description", "status", "video_url", "thumbnail_url", "platforms", "posted_platforms", "scheduled_for", "posted_at", "error_message", "platform_errors" ], "description": "A video post record" } }, "required": [ "video" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/videos/{videoId}": { "get": { "operationId": "getVideo", "summary": "Retrieve a video", "description": "Fetch a single video post by ID.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "videoId", "in": "path" } ], "responses": { "200": { "description": "The video.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "title", "description", "status", "video_url", "thumbnail_url", "platforms", "posted_platforms", "scheduled_for", "posted_at", "error_message", "platform_errors" ], "description": "A video post record" } }, "required": [ "video" ] } }, "required": [ "success", "data" ] } } } } } }, "put": { "operationId": "updateVideo", "summary": "Update a video", "description": "Update title, description, platforms, or scheduling for a video post.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "videoId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" } }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" } }, "description": "Partial update of a video post" } } } }, "responses": { "200": { "description": "Video updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "title", "description", "status", "video_url", "thumbnail_url", "platforms", "posted_platforms", "scheduled_for", "posted_at", "error_message", "platform_errors" ], "description": "A video post record" } }, "required": [ "video" ] } }, "required": [ "success", "data" ] } } } } } }, "delete": { "operationId": "deleteVideo", "summary": "Delete a video", "description": "Permanently deletes a video post.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "videoId", "in": "path" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/stories/{storyId}": { "get": { "operationId": "getStory", "summary": "Retrieve a story", "description": "Fetch a single Story by ID.", "tags": [ "Stories" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "storyId", "in": "path" } ], "responses": { "200": { "description": "Story record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "story": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "story_type": { "type": "string", "enum": [ "image", "video" ], "description": "Story media type" }, "image_url": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "duration": { "type": [ "number", "null" ] }, "aspect_ratio": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "platforms": { "type": "array", "items": { "type": "string" } }, "posted_platforms": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "source_post_id": { "type": [ "string", "null" ] }, "source_video_id": { "type": [ "string", "null" ] }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "story_type", "image_url", "video_url", "thumbnail_url", "duration", "aspect_ratio", "caption", "platforms", "posted_platforms", "status", "scheduled_for", "posted_at", "expires_at", "error_message", "platform_errors", "platform_post_ids", "source_post_id", "source_video_id", "facebook_target" ], "description": "A Story record — short-lived (24h) content for Instagram, Facebook, or TikTok" } }, "required": [ "story" ] } }, "required": [ "success", "data" ] } } } } } }, "delete": { "operationId": "deleteStory", "summary": "Delete a story", "description": "Delete a Story. The underlying media is not deleted — managed externally by the caller.", "tags": [ "Stories" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "storyId", "in": "path" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/posts/generate": { "post": { "operationId": "generatePost", "summary": "Generate a post", "description": "Uses the content group's brand profile (tone, audience, topics) to generate a new post via AI. Counts as 1 AI text generation.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contentGroupId": { "type": "string", "description": "Content group to generate for — brand profile is used" }, "generateImage": { "type": "boolean", "description": "Also generate an AI image. Costs 1 image credit." } }, "required": [ "contentGroupId" ] } } } }, "responses": { "201": { "description": "Post generated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "required": [ "success", "data" ] } } } }, "403": { "description": "Monthly limit exceeded." } } } }, "/v1/posts/create": { "post": { "operationId": "createPost", "summary": "Create a post", "description": "Manually create a post with your own content. Supports text, image, and carousel post types. Media URLs must be publicly accessible.\n\nFor video / Reels (TikTok, YouTube, Instagram Reels, Facebook Reels, X, Threads, LinkedIn), use POST /v1/videos instead — postType=\"video\" is not accepted here.\n\nAttaching a raw file you have inline (e.g. a file the user uploaded to Claude/ChatGPT): first call `uploadImage` with the base64 `data` to get a public `imageUrl`, then pass that here. Posting an existing image already on the web works too — call `uploadImage` with `sourceUrl` first so the URL ends up on a TikTok-whitelisted domain.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contentGroupId": { "type": "string", "description": "Content group (app) that owns this post" }, "content": { "type": "string", "description": "Post body text / caption" }, "postType": { "type": "string", "enum": [ "text", "image", "carousel" ] }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" } }, "imageUrl": { "type": "string", "format": "uri", "description": "Required for postType=image" }, "imageUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Required for postType=carousel" }, "isDraft": { "type": "boolean", "description": "Save as draft instead of pending. Default false." }, "scheduledFor": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp for scheduling" }, "linkedinTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebookTarget": { "type": "object", "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "threadParts": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" }, "description": "Reply-based thread parts for twitter_x / threads / bluesky. Minimum 2. Other platforms only post the first part." } }, "required": [ "contentGroupId", "content", "postType" ] } } } }, "responses": { "201": { "description": "Post created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/posts/{postId}": { "get": { "operationId": "getPost", "summary": "Retrieve a post", "description": "Fetch a single post by ID.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Post ID" }, "required": true, "description": "Post ID", "name": "postId", "in": "path" } ], "responses": { "200": { "description": "The post.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Post not found." } } }, "put": { "operationId": "updatePost", "summary": "Update a post", "description": "Update content, platforms, media, scheduling, or thread parts on an existing post.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Post ID" }, "required": true, "description": "Post ID", "name": "postId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "postType": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" } }, "imageUrl": { "type": [ "string", "null" ] }, "imageUrls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "videoUrl": { "type": [ "string", "null" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "linkedinTarget": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebookTarget": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "threadParts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } } }, "description": "Partial update — only provided fields change" } } } }, "responses": { "200": { "description": "Post updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "required": [ "success", "data" ] } } } } } }, "patch": { "operationId": "patchPost", "summary": "Patch a post", "description": "Partial update — only provided fields change. Refuses with 409 if the post has already been published (the platforms would not reflect the change).", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Post ID" }, "required": true, "description": "Post ID", "name": "postId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "postType": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" } }, "imageUrl": { "type": [ "string", "null" ] }, "imageUrls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "videoUrl": { "type": [ "string", "null" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "linkedinTarget": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebookTarget": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "threadParts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } } }, "description": "Partial update — only provided fields change" } } } }, "responses": { "200": { "description": "Post updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "required": [ "success", "data" ] } } } }, "409": { "description": "Post has already been published and cannot be edited." } } }, "delete": { "operationId": "deletePost", "summary": "Delete a post", "description": "Permanently deletes a post. Cannot be undone.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Post ID" }, "required": true, "description": "Post ID", "name": "postId", "in": "path" } ], "responses": { "200": { "description": "Post deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/images/upload": { "post": { "operationId": "uploadImage", "summary": "Upload an image", "description": "Uploads an image to PostQuickAI storage and returns a public URL hosted on a domain whitelisted by our TikTok developer app. Use this to host externally-generated carousel slides (or any image) on a URL that TikTok will accept when publishing via /v1/posts/create.\n\nAccepts three input shapes:\n- multipart/form-data with a `file` field — direct binary upload (best for browsers / curl).\n- application/json with a `data` field — base64-encoded raw bytes (best for MCP clients / Claude / ChatGPT that have a file inline but cannot send multipart). Optionally include `contentType` and `fileName`.\n- application/json with a `sourceUrl` field — server fetches and re-hosts a public URL (best for re-hosting from your own CDN).\n\nLimits: image/jpeg, image/png, image/webp, image/gif. Max 10MB. Counts against your storage quota.\n\nTypical MCP flow: call `uploadImage` with base64 `data` → take the returned `imageUrl` → pass it as `imageUrl` to `createPost` (or as one entry in `imageUrls` for a carousel).", "tags": [ "Images" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "Image file. Allowed: image/jpeg, image/png, image/webp, image/gif. Max 10MB.", "format": "binary" } }, "required": [ "file" ] } }, "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "Raw image bytes encoded as base64. Accepts either a plain base64 string or a full data URL (e.g. \"data:image/png;base64,...\"). Use this when an MCP client (Claude, ChatGPT, etc.) has the file inline and cannot send multipart/form-data. Max 10MB decoded." }, "contentType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif" ], "description": "MIME type of the inline `data` payload. Optional — the server falls back to the data-URL prefix or magic-byte sniffing if omitted, but providing it is the most reliable." }, "fileName": { "type": "string", "description": "Optional original file name. Used only to derive a fallback extension." }, "sourceUrl": { "type": "string", "format": "uri", "description": "Publicly accessible image URL to fetch and re-host on PostQuickAI storage. Use this instead of `data` when the image is already hosted somewhere (Cloudinary, S3, your CDN). The resulting URL is on a TikTok-whitelisted domain." } } } } } }, "responses": { "201": { "description": "Image uploaded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "imageUrl": { "type": "string", "format": "uri", "description": "Public URL of the hosted image. Safe to pass to /v1/posts/create as imageUrl / imageUrls." }, "contentType": { "type": "string", "description": "Detected image MIME type" }, "size": { "type": "integer", "description": "Image size in bytes" } }, "required": [ "imageUrl", "contentType", "size" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Invalid request (missing file/sourceUrl, unsupported type, oversized)." }, "403": { "description": "Storage limit exceeded." } } } }, "/v1/images/generate": { "post": { "operationId": "generateImage", "summary": "Generate an image", "description": "Generate an AI image via Gemini Flash (default), GPT Image 2, or Nano Banana Pro. Image is uploaded to Supabase Storage; response includes a public URL.", "tags": [ "Images" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Detailed image prompt" }, "model": { "type": "string", "enum": [ "gemini-flash", "gpt-image-1.5", "nano-banana-pro" ], "description": "Image generation model" }, "aspectRatio": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "3:4", "4:3" ] }, "contentGroupId": { "type": "string", "description": "Ground in brand visual style" } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "Generated image.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "imageUrl": { "type": "string", "format": "uri" }, "model": { "type": "string" }, "aspectRatio": { "type": "string" } }, "required": [ "imageUrl", "model" ] } }, "required": [ "success", "data" ] } } } }, "403": { "description": "Monthly image generation limit exceeded." } } } }, "/v1/hashtags/generate": { "post": { "operationId": "generateHashtags", "summary": "Generate hashtags", "description": "AI-generated hashtags optimized for the target platform. Platform-specific defaults: Instagram=30, Twitter=1-2, LinkedIn=3-5.", "tags": [ "AI Content" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "platform": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" }, "count": { "type": "integer", "minimum": 1, "maximum": 30 }, "contentGroupId": { "type": "string" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Hashtags.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "hashtags": { "type": "array", "items": { "type": "string" } }, "platform": { "type": "string" }, "count": { "type": "number" } }, "required": [ "hashtags", "count" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content-groups/{groupId}": { "get": { "operationId": "getContentGroup", "summary": "Retrieve a content group", "description": "Returns a single content group with its associated platforms, social accounts, and brand instructions.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group UUID" }, "required": true, "description": "Content group UUID", "name": "groupId", "in": "path" } ], "responses": { "200": { "description": "The content group.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "contentGroup": { "type": "object", "properties": { "id": { "type": "string" }, "user_id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "user_id", "name" ], "description": "A content group (a.k.a. \"app\" — a brand/project container)" } }, "required": [ "contentGroup" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Content group not found." } } }, "delete": { "operationId": "deleteContentGroup", "summary": "Delete a content group", "description": "Permanently deletes a content group and all its associated posts. Social account connections are preserved.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group UUID" }, "required": true, "description": "Content group UUID", "name": "groupId", "in": "path" } ], "responses": { "200": { "description": "Content group deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Content group not found." } } } }, "/v1/content/proofread": { "post": { "operationId": "proofread", "summary": "Proofread", "description": "Grammar and spelling fixes while preserving voice and style.", "tags": [ "AI Content" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Proofread content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "proofreadContent": { "type": "string" } }, "required": [ "proofreadContent" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content/custom-edit": { "post": { "operationId": "customEdit", "summary": "Custom edit", "description": "Apply a free-form natural-language edit to existing copy.", "tags": [ "AI Content" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "instruction": { "type": "string", "description": "Natural-language editing instruction (e.g. \"add emojis and a CTA\")" }, "contentGroupId": { "type": "string" } }, "required": [ "content", "instruction" ] } } } }, "responses": { "200": { "description": "Edited content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "editedContent": { "type": "string" } }, "required": [ "editedContent" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content/make-concise": { "post": { "operationId": "makeConcise", "summary": "Make concise", "description": "Tighten copy while preserving meaning. Useful for Twitter/X 280-char limit.", "tags": [ "AI Content" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "maxLength": { "type": "integer", "description": "Target character count" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Concise version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "conciseContent": { "type": "string" } }, "required": [ "conciseContent" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content/adjust-tone": { "post": { "operationId": "adjustTone", "summary": "Adjust tone", "description": "Rewrite existing copy in a different tone while preserving meaning.", "tags": [ "AI Content" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "tone": { "type": "string", "description": "Target tone (e.g. \"professional\", \"witty\", \"warm\")" }, "contentGroupId": { "type": "string" } }, "required": [ "content", "tone" ] } } } }, "responses": { "200": { "description": "Tone-adjusted content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "adjustedContent": { "type": "string" } }, "required": [ "adjustedContent" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/captions/video": { "post": { "operationId": "generateVideoCaption", "summary": "Generate a video caption", "description": "Generate an engaging caption for a video post (hooks, CTAs, optimized for TikTok/Reels/Shorts).", "tags": [ "AI Content" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string" }, "contentGroupId": { "type": "string" } }, "required": [ "topic" ] } } } }, "responses": { "200": { "description": "Video caption.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "caption": { "type": "string" } }, "required": [ "caption" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/captions/generate": { "post": { "operationId": "generateCaption", "summary": "Generate a caption", "description": "Generate a social media caption with AI, optionally grounded in a content group's brand profile. Counts as 1 AI text generation.", "tags": [ "AI Content" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string" }, "platform": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" }, "contentGroupId": { "type": "string", "description": "Ground the caption in this brand profile" }, "tone": { "type": "string" }, "maxLength": { "type": "integer" } }, "required": [ "topic" ] } } } }, "responses": { "200": { "description": "Generated caption.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "caption": { "type": "string" } }, "required": [ "caption" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/captions/carousel": { "post": { "operationId": "generateCarouselCaption", "summary": "Generate a carousel caption", "description": "Generate a caption specifically tailored for a multi-slide carousel post.", "tags": [ "AI Content" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string" }, "slideCount": { "type": "integer", "minimum": 2, "maximum": 10 }, "contentGroupId": { "type": "string" } }, "required": [ "topic" ] } } } }, "responses": { "200": { "description": "Carousel caption.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "caption": { "type": "string" } }, "required": [ "caption" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/accounts/{accountId}": { "delete": { "operationId": "disconnectAccount", "summary": "Disconnect a social account", "description": "Permanently disconnect a social account. Deletes stored OAuth tokens. Re-connecting requires the dashboard OAuth flow.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "accountId", "in": "path" } ], "responses": { "200": { "description": "Disconnected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhookEndpoint", "summary": "Send a test event to an endpoint", "description": "Queue a synthetic `post.posted` event with `data.test=true` for immediate dispatch. The dispatch cron picks up pending deliveries every minute, so the receiver should observe the test within ~60 seconds. Useful for sanity-checking a newly-registered endpoint without waiting for real publish activity.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "202": { "description": "Test delivery queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "next_attempt_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "event", "status", "created_at", "next_attempt_at" ] }, "message": { "type": "string" } }, "required": [ "delivery", "message" ] } }, "required": [ "success", "data" ] } } } }, "409": { "description": "Endpoint is inactive; re-enable via PATCH before testing." } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate a webhook signing secret", "description": "Generate a new signing secret for an endpoint. Returns plaintext EXACTLY ONCE. The old secret is invalidated immediately — in-flight deliveries signed with it will fail signature verification on the receiver. For zero-downtime rotation, register a second endpoint with a new secret, migrate traffic, then delete the original.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Rotated. Response includes the new plaintext signing secret.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "endpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed events (e.g. [\"post.partial\"]) or [\"*\"] for all." }, "active": { "type": "boolean" }, "secret_preview": { "type": "string", "description": "First 8 chars of the signing secret. Useful for identifying which secret an endpoint uses without exposing it." }, "consecutive_failures": { "type": "integer", "description": "Count of consecutive failed deliveries. Auto-disables the endpoint at 50; resets to 0 on the first 2xx response." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "url", "events", "active", "secret_preview", "consecutive_failures", "created_at", "updated_at" ], "description": "A registered webhook endpoint." }, "secret": { "type": "string" }, "secret_notice": { "type": "string" } }, "required": [ "endpoint", "secret", "secret_notice" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List delivery attempts for an endpoint", "description": "Inspect delivery history for an endpoint. Filter by `status` (pending, delivering, succeeded, failed_retrying, failed) and/or `subject_id` (the post/video/story this event was about). Last 30 days are retained.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "pending", "delivering", "succeeded", "failed_retrying", "failed" ], "description": "Delivery lifecycle: pending → delivering → (succeeded | failed_retrying → failed)." }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "subject_id", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Array of delivery records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Delivery UUID — mirrored in the `X-PostQuickAI-Delivery-Id` header. Stable across retries; use for receiver-side dedup." }, "endpoint_id": { "type": "string", "format": "uuid" }, "event": { "type": "string" }, "subject_id": { "type": [ "string", "null" ], "format": "uuid" }, "subject_type": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "delivering", "succeeded", "failed_retrying", "failed" ], "description": "Delivery lifecycle: pending → delivering → (succeeded | failed_retrying → failed)." }, "attempt_count": { "type": "integer" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "last_http_status": { "type": [ "integer", "null" ] }, "last_response_body": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "endpoint_id", "event", "subject_id", "subject_type", "status", "attempt_count", "next_attempt_at", "last_http_status", "last_response_body", "last_error", "created_at", "delivered_at" ], "description": "One delivery attempt for a webhook event." } } }, "required": [ "deliveries" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/videos/{videoId}/status": { "get": { "operationId": "getVideoStatus", "summary": "Check video status", "description": "Poll the generation status of a video. Returns status (pending/generating/draft/failed), progress, and the final video URL when ready.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "videoId", "in": "path" } ], "responses": { "200": { "description": "Status snapshot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "status": { "type": "string" }, "videoUrl": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "progress": { "type": "number" } }, "required": [ "status" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/videos/{videoId}/schedule": { "post": { "operationId": "scheduleVideo", "summary": "Schedule a video", "description": "Schedule a video post for future publishing.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "videoId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledFor": { "type": "string", "format": "date-time" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" } }, "facebookTarget": { "type": "object", "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "linkedinTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" } }, "required": [ "scheduledFor" ] } } } }, "responses": { "200": { "description": "Scheduled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "title", "description", "status", "video_url", "thumbnail_url", "platforms", "posted_platforms", "scheduled_for", "posted_at", "error_message", "platform_errors" ], "description": "A video post record" } }, "required": [ "video" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/videos/{videoId}/reset-platforms": { "post": { "operationId": "resetVideoPlatforms", "summary": "Reset video posted platforms", "description": "Clear posted_platforms/error_message on a video so it can be republished.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "videoId", "in": "path" } ], "responses": { "200": { "description": "Reset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "title", "description", "status", "video_url", "thumbnail_url", "platforms", "posted_platforms", "scheduled_for", "posted_at", "error_message", "platform_errors" ], "description": "A video post record" } }, "required": [ "video" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/videos/{videoId}/publish": { "post": { "operationId": "publishVideo", "summary": "Publish a video", "description": "Immediately publish a video to TikTok, YouTube, Instagram Reels, or Twitter/X.", "tags": [ "Videos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "videoId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" }, "description": "Target platforms. Defaults to the platforms set on the video at create time." }, "facebookTarget": { "type": "object", "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "linkedinTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" } } } } } }, "responses": { "200": { "description": "Publish result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "title", "description", "status", "video_url", "thumbnail_url", "platforms", "posted_platforms", "scheduled_for", "posted_at", "error_message", "platform_errors" ], "description": "A video post record" } }, "required": [ "video" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/stories/from-post/{postId}": { "post": { "operationId": "convertToStory", "summary": "Convert a post or video into a Story", "description": "Create a Story draft that reuses media from an existing post (or video post). The source media is referenced, not re-uploaded, and usage is NOT charged again — the underlying file was already counted against the user's quota when the source was created. Use the source query parameter to choose between generated_posts (default) and video_posts.", "tags": [ "Stories" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "postId", "in": "path" }, { "schema": { "type": "string", "enum": [ "post", "video" ], "description": "Source table. Defaults to \"post\" (generated_posts)." }, "required": false, "description": "Source table. Defaults to \"post\" (generated_posts).", "name": "source", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "facebook", "tiktok" ], "description": "Platform that supports Stories" } }, "caption": { "type": "string", "description": "Override the inherited caption. Falls back to the source content/description." } } } } } }, "responses": { "201": { "description": "Story draft created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "story": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "story_type": { "type": "string", "enum": [ "image", "video" ], "description": "Story media type" }, "image_url": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "duration": { "type": [ "number", "null" ] }, "aspect_ratio": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "platforms": { "type": "array", "items": { "type": "string" } }, "posted_platforms": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "source_post_id": { "type": [ "string", "null" ] }, "source_video_id": { "type": [ "string", "null" ] }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "story_type", "image_url", "video_url", "thumbnail_url", "duration", "aspect_ratio", "caption", "platforms", "posted_platforms", "status", "scheduled_for", "posted_at", "expires_at", "error_message", "platform_errors", "platform_post_ids", "source_post_id", "source_video_id", "facebook_target" ], "description": "A Story record — short-lived (24h) content for Instagram, Facebook, or TikTok" } }, "required": [ "story" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/stories/{storyId}/schedule": { "post": { "operationId": "scheduleStory", "summary": "Schedule a story", "description": "Schedule a Story for future publishing. The /api/cron/publish-scheduled handler picks it up at or after scheduledFor.", "tags": [ "Stories" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "storyId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledFor": { "type": "string", "format": "date-time", "description": "ISO timestamp in the future." }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "facebook", "tiktok" ], "description": "Platform that supports Stories" }, "minItems": 1 }, "tiktokSettings": { "type": "object", "additionalProperties": {} }, "facebookTarget": { "type": "object", "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" } }, "required": [ "scheduledFor", "platforms" ] } } } }, "responses": { "200": { "description": "Scheduled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "story": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "story_type": { "type": "string", "enum": [ "image", "video" ], "description": "Story media type" }, "image_url": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "duration": { "type": [ "number", "null" ] }, "aspect_ratio": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "platforms": { "type": "array", "items": { "type": "string" } }, "posted_platforms": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "source_post_id": { "type": [ "string", "null" ] }, "source_video_id": { "type": [ "string", "null" ] }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "story_type", "image_url", "video_url", "thumbnail_url", "duration", "aspect_ratio", "caption", "platforms", "posted_platforms", "status", "scheduled_for", "posted_at", "expires_at", "error_message", "platform_errors", "platform_post_ids", "source_post_id", "source_video_id", "facebook_target" ], "description": "A Story record — short-lived (24h) content for Instagram, Facebook, or TikTok" } }, "required": [ "story" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/stories/{storyId}/publish": { "post": { "operationId": "publishStory", "summary": "Publish a story", "description": "Dispatch a Story for immediate publishing to Instagram, Facebook, and/or TikTok. Returns 202 — the publish job runs in the background. Poll GET /v1/stories/{storyId} for final status.", "tags": [ "Stories" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "storyId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "facebook", "tiktok" ], "description": "Platform that supports Stories" }, "minItems": 1 }, "tiktokSettings": { "type": "object", "additionalProperties": {} }, "facebookTarget": { "type": "object", "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" } }, "required": [ "platforms" ] } } } }, "responses": { "202": { "description": "Publish initiated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "storyId": { "type": "string" }, "status": { "type": "string", "enum": [ "processing" ] }, "message": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } } }, "required": [ "storyId", "status", "message", "platforms" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/posts/{postId}/schedule": { "post": { "operationId": "schedulePost", "summary": "Schedule a post", "description": "Schedule a post for future publishing. Cron picks it up and publishes automatically.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "postId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contentGroupId": { "type": "string" }, "scheduledFor": { "type": "string", "format": "date-time", "description": "ISO 8601 time. Must be at least 5 min in the future." }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" } } }, "required": [ "contentGroupId", "scheduledFor" ] } } } }, "responses": { "200": { "description": "Scheduled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/posts/{postId}/reset-platforms": { "post": { "operationId": "resetPostPlatforms", "summary": "Reset posted platforms", "description": "Clear posted_platforms and error_message so the post can be republished cleanly. Useful after fixing a failed publish.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "postId", "in": "path" } ], "responses": { "200": { "description": "Platforms reset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/posts/{postId}/regenerate": { "post": { "operationId": "regeneratePost", "summary": "Regenerate a post", "description": "Rewrite an existing post with AI based on natural-language feedback. Optionally regenerate the image.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "postId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "type": "string", "minLength": 1, "description": "Feedback guiding the rewrite" }, "generateImage": { "type": "boolean" }, "imageModel": { "type": "string", "enum": [ "gemini-flash", "gpt-image-1.5", "nano-banana-pro" ], "description": "Image generation model" } }, "required": [ "instructions" ] } } } }, "responses": { "200": { "description": "Post regenerated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/posts/{postId}/images": { "put": { "operationId": "updatePostImages", "summary": "Update post images", "description": "Attach, replace, or remove images on a post.\n\nAttaching a raw file you have inline: first call `uploadImage` with the base64 `data` to get a public `imageUrl`, then call this endpoint with action `set_single_image` (or `set_multiple_images` for a carousel).", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "postId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "set_single_image", "set_multiple_images", "remove_all_images", "remove_single_image" ] }, "imageUrl": { "type": "string", "format": "uri" }, "imageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "action" ] } } } }, "responses": { "200": { "description": "Images updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/posts/{postId}/publish": { "post": { "operationId": "publishPost", "summary": "Publish a post", "description": "Immediately publish a post to the specified platforms. Returns success/failure per platform.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "postId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter_x", "twitter", "threads", "bluesky", "linkedin", "facebook", "instagram", "youtube", "tiktok" ], "description": "Social platform identifier" }, "minItems": 1, "description": "Platforms to publish to" }, "linkedinTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebookTarget": { "type": "object", "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" } }, "required": [ "platforms" ] } } } }, "responses": { "200": { "description": "Publish result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "draft", "scheduled", "processing", "posted", "published", "partial", "failed" ], "description": "Post lifecycle status. `partial` indicates at least one targeted platform succeeded and at least one failed — check `platform_errors` for the per-platform breakdown." }, "post_type": { "type": "string", "enum": [ "text", "image", "carousel", "video" ], "description": "Post content type" }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posted_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "image_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "video_url": { "type": [ "string", "null" ] }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "thread_parts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "text": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "video_url": { "type": "string", "format": "uri" }, "post_type": { "type": "string", "enum": [ "text", "image", "video" ] } }, "required": [ "text" ], "description": "One part of a reply-based thread" } }, "linkedin_target": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "personal", "organization" ] }, "organizationId": { "type": "string" } }, "required": [ "type" ], "description": "LinkedIn publishing target" }, "facebook_target": { "type": [ "object", "null" ], "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" } }, "required": [ "pageId" ], "description": "Facebook page publishing target" }, "platform_post_ids": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "error_message": { "type": [ "string", "null" ] }, "platform_errors": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Per-platform error messages keyed by platform name. Populated when `status` is `partial` or `failed`." }, "is_manual": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "content", "status", "post_type", "platforms", "posted_platforms", "image_url", "image_urls", "video_url", "scheduled_for", "posted_at", "thread_parts", "linkedin_target", "facebook_target", "platform_post_ids", "error_message", "platform_errors", "is_manual" ], "description": "A social media post record" }, "publishedTo": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "error": { "type": "string" } }, "required": [ "platform", "error" ] } } }, "required": [ "post", "publishedTo" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/posts/{postId}/analytics": { "get": { "operationId": "getPostAnalytics", "summary": "Post analytics", "description": "Per-platform social performance metrics (views, likes, comments, shares, saves) for a post, plus 30-day history.", "tags": [ "Posts", "Analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "postId", "in": "path" }, { "schema": { "type": "string", "enum": [ "post", "video" ], "description": "Which table. Default \"post\"." }, "required": false, "description": "Which table. Default \"post\".", "name": "type", "in": "query" } ], "responses": { "200": { "description": "Analytics payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "postId": { "type": "string" }, "postType": { "type": "string" }, "totals": { "type": "object", "properties": { "views": { "type": "number" }, "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" }, "saves": { "type": "number" }, "engagementRate": { "type": "number" } }, "required": [ "views", "likes", "comments", "shares", "saves", "engagementRate" ] }, "platforms": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "history": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "lastFetched": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "postId", "postType", "totals", "platforms", "history", "lastFetched" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/instruction-proposals/{proposalId}/reject": { "post": { "operationId": "rejectInstructionProposal", "summary": "Reject an instruction proposal", "description": "Dismiss a proposed instruction edit without applying it. No change is written.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Proposal ID" }, "required": true, "description": "Proposal ID", "name": "proposalId", "in": "path" } ], "responses": { "200": { "description": "The rejected proposal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "proposal": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "job_id": { "type": [ "string", "null" ] }, "field": { "type": "string", "description": "The content_instructions field to change." }, "current_value": { "type": [ "string", "null" ] }, "proposed_value": { "type": "string" }, "reason": { "type": "string" }, "evidence": { "type": "array", "items": {}, "description": "Popular-post URLs justifying the edit." }, "status": { "type": "string", "enum": [ "proposed", "approved", "rejected", "superseded" ] }, "created_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "decided_by": { "type": [ "string", "null" ] } }, "required": [ "id", "app_id", "job_id", "field", "current_value", "proposed_value", "reason", "evidence", "status" ], "description": "A proposed edit to a content group's instructions." } }, "required": [ "proposal" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/instruction-proposals/{proposalId}/approve": { "post": { "operationId": "approveInstructionProposal", "summary": "Approve an instruction proposal", "description": "Apply a proposed instruction edit: write the new value, log it to the audit trail, and mark the proposal approved. Returns the applied change.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Proposal ID" }, "required": true, "description": "Proposal ID", "name": "proposalId", "in": "path" } ], "responses": { "200": { "description": "The applied change.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "change": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "field": { "type": "string" }, "old_value": { "type": [ "string", "null" ] }, "new_value": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "agent", "user" ] }, "proposal_id": { "type": [ "string", "null" ] }, "applied_at": { "type": "string", "format": "date-time" } }, "description": "An applied (or reverted) instruction change — the audit trail." } }, "required": [ "change" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/instruction-changes/{changeId}/revert": { "post": { "operationId": "revertInstructionChange", "summary": "Revert an instruction change", "description": "Undo an applied instruction change by restoring the previous value. The reversal is itself logged as a new change (append-only history), so it too can be undone.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Change ID to revert" }, "required": true, "description": "Change ID to revert", "name": "changeId", "in": "path" } ], "responses": { "200": { "description": "The reversal change record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "change": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "field": { "type": "string" }, "old_value": { "type": [ "string", "null" ] }, "new_value": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "agent", "user" ] }, "proposal_id": { "type": [ "string", "null" ] }, "applied_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "field", "old_value", "new_value", "reason", "source", "proposal_id" ], "description": "An applied (or reverted) instruction change — the audit trail." } }, "required": [ "change" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content-groups/{groupId}/trending": { "get": { "operationId": "searchTrendingContent", "summary": "Search popular niche content", "description": "Look up the most popular content in this content group's niche across social platforms. The niche is derived from the group's brand instructions (topics + target audience). Each platform returns up to `limit` posts; platforms without an available API (or pending app review) appear under `unavailable` with a reason.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group ID" }, "required": true, "description": "Content group ID", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "description": "Comma-separated platforms (e.g. youtube,x,bluesky). Defaults to all." }, "required": false, "description": "Comma-separated platforms (e.g. youtube,x,bluesky). Defaults to all.", "name": "platforms", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Max results per platform (default 10, max 25)." }, "required": false, "description": "Max results per platform (default 10, max 25).", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Popular niche content per platform.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "niche": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string" } }, "required": [ "keywords", "topics" ] }, "results": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "youtube", "bluesky", "x", "threads", "instagram", "tiktok", "facebook", "linkedin" ], "description": "Platform the trend search can target" }, "url": { "type": "string", "description": "Canonical link to the original post." }, "author": { "type": "string" }, "text": { "type": "string", "description": "Caption/body snippet of the post." }, "metrics": { "type": "object", "properties": { "views": { "type": "number" }, "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" } } }, "postedAt": { "type": "string" }, "mediaType": { "type": "string", "enum": [ "text", "image", "video", "carousel" ] }, "thumbnailUrl": { "type": "string" } }, "required": [ "platform", "url", "text", "metrics" ], "description": "A popular post found in the niche, normalised across platforms." } }, "description": "Popular posts keyed by platform." }, "unavailable": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Platforms that could not be queried, keyed by platform, with a human-readable reason (missing key, pending app review, rate limit, or no API)." } }, "required": [ "niche", "results", "unavailable" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content-groups/{groupId}/instructions": { "get": { "operationId": "getInstructions", "summary": "Get brand instructions", "description": "Retrieves the brand profile + generation settings for a content group (brand_name, tone, target audience, topics, auto-generation flags, YOLO mode, etc.).", "tags": [ "Content Groups", "Instructions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group UUID" }, "required": true, "description": "Content group UUID", "name": "groupId", "in": "path" } ], "responses": { "200": { "description": "Brand instructions (null if not set).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "instructions": { "type": [ "object", "null" ], "properties": { "app_id": { "type": "string" }, "user_id": { "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "target_audience": { "type": [ "string", "null" ] }, "tone": { "type": [ "string", "null" ] }, "topics": { "type": [ "string", "null" ] }, "instructions": { "type": [ "string", "null" ] }, "image_instructions": { "type": [ "string", "null" ] }, "include_image": { "type": [ "boolean", "null" ] }, "image_model": { "type": [ "string", "null" ] }, "auto_generate": { "type": [ "boolean", "null" ] }, "yolo_mode": { "type": [ "boolean", "null" ] }, "yolo_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "generate_carousels": { "type": [ "boolean", "null" ] }, "generate_videos": { "type": [ "boolean", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] } }, "required": [ "app_id", "user_id", "brand_name", "target_audience", "tone", "topics", "instructions", "image_instructions", "include_image", "image_model", "auto_generate", "yolo_mode", "yolo_platforms", "generate_carousels", "generate_videos", "website_url", "language" ], "description": "Brand profile + generation settings for a content group" } }, "required": [ "instructions" ] } }, "required": [ "success", "data" ] } } } } } }, "put": { "operationId": "updateInstructions", "summary": "Update brand instructions", "description": "Create or update brand profile fields for a content group. Upsert — any subset of fields can be passed.", "tags": [ "Content Groups", "Instructions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group UUID" }, "required": true, "description": "Content group UUID", "name": "groupId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "type": "string" }, "brand_name": { "type": "string" }, "target_audience": { "type": "string" }, "tone": { "type": "string" }, "topics": { "type": "string" }, "extra_info": { "type": "string" }, "include_image": { "type": "boolean" }, "image_model": { "type": "string" }, "image_instructions": { "type": "string" }, "use_website_images": { "type": "boolean" }, "frequency": { "type": "string" }, "auto_generate": { "type": "boolean" }, "generate_carousels": { "type": "boolean" }, "generate_videos": { "type": "boolean" }, "carousel_instructions": { "type": "string" }, "carousel_platforms": { "type": "array", "items": { "type": "string" } }, "video_instructions": { "type": "string" }, "video_platforms": { "type": "array", "items": { "type": "string" } }, "yolo_mode": { "type": "boolean" }, "yolo_platforms": { "type": "array", "items": { "type": "string" } }, "website_url": { "type": "string" }, "linkedin_target": { "type": "object", "additionalProperties": {} }, "facebook_target": { "type": "object", "additionalProperties": {} }, "media_source": { "type": "string" }, "user_media_ids": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string" } }, "description": "Partial update of brand profile fields" } } } }, "responses": { "200": { "description": "Instructions saved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "instructions": { "type": "object", "properties": { "app_id": { "type": "string" }, "user_id": { "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "target_audience": { "type": [ "string", "null" ] }, "tone": { "type": [ "string", "null" ] }, "topics": { "type": [ "string", "null" ] }, "instructions": { "type": [ "string", "null" ] }, "image_instructions": { "type": [ "string", "null" ] }, "include_image": { "type": [ "boolean", "null" ] }, "image_model": { "type": [ "string", "null" ] }, "auto_generate": { "type": [ "boolean", "null" ] }, "yolo_mode": { "type": [ "boolean", "null" ] }, "yolo_platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "generate_carousels": { "type": [ "boolean", "null" ] }, "generate_videos": { "type": [ "boolean", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] } }, "required": [ "app_id", "user_id", "brand_name", "target_audience", "tone", "topics", "instructions", "image_instructions", "include_image", "image_model", "auto_generate", "yolo_mode", "yolo_platforms", "generate_carousels", "generate_videos", "website_url", "language" ], "description": "Brand profile + generation settings for a content group" } }, "required": [ "instructions" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content-groups/{groupId}/instruction-proposals": { "get": { "operationId": "listInstructionProposals", "summary": "List instruction-edit proposals", "description": "List the self-improving loop's proposed instruction edits for a content group. Filter by status to show, e.g., only the pending queue (status=proposed).", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group ID" }, "required": true, "description": "Content group ID", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "enum": [ "proposed", "approved", "rejected", "superseded" ], "description": "Filter by proposal status." }, "required": false, "description": "Filter by proposal status.", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Array of proposals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "proposals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "job_id": { "type": [ "string", "null" ] }, "field": { "type": "string", "description": "The content_instructions field to change." }, "current_value": { "type": [ "string", "null" ] }, "proposed_value": { "type": "string" }, "reason": { "type": "string" }, "evidence": { "type": "array", "items": {}, "description": "Popular-post URLs justifying the edit." }, "status": { "type": "string", "enum": [ "proposed", "approved", "rejected", "superseded" ] }, "created_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "decided_by": { "type": [ "string", "null" ] } }, "required": [ "id", "app_id", "job_id", "field", "current_value", "proposed_value", "reason", "evidence", "status" ], "description": "A proposed edit to a content group's instructions." } } }, "required": [ "proposals" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content-groups/{groupId}/instruction-changes": { "get": { "operationId": "listInstructionChanges", "summary": "List instruction change history", "description": "The audit trail: every applied (or reverted) instruction change for a content group, newest first, with before/after, reason, and source (agent/user).", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group ID" }, "required": true, "description": "Content group ID", "name": "groupId", "in": "path" } ], "responses": { "200": { "description": "Array of changes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "field": { "type": "string" }, "old_value": { "type": [ "string", "null" ] }, "new_value": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "agent", "user" ] }, "proposal_id": { "type": [ "string", "null" ] }, "applied_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "field", "old_value", "new_value", "reason", "source", "proposal_id" ], "description": "An applied (or reverted) instruction change — the audit trail." } } }, "required": [ "changes" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content-groups/{groupId}/analytics": { "get": { "operationId": "getGroupAnalytics", "summary": "Group analytics", "description": "Aggregate social performance analytics for all posts in a content group. Breaks down by platform, content type, and includes top posts + daily trend.", "tags": [ "Content Groups", "Analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group UUID" }, "required": true, "description": "Content group UUID", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "description": "Time window. Default: 30d." }, "required": false, "description": "Time window. Default: 30d.", "name": "period", "in": "query" }, { "schema": { "type": "string", "description": "Max number of topPosts to return. Default 10, clamped to [1, 100]." }, "required": false, "description": "Max number of topPosts to return. Default 10, clamped to [1, 100].", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Alias for `limit`. Use either; `limit` wins if both are passed." }, "required": false, "description": "Alias for `limit`. Use either; `limit` wins if both are passed.", "name": "postsLimit", "in": "query" } ], "responses": { "200": { "description": "Aggregate analytics.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "groupId": { "type": "string" }, "groupName": { "type": "string" }, "period": { "type": "string" }, "totals": { "type": "object", "properties": { "views": { "type": "number" }, "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" }, "saves": { "type": "number" }, "engagementRate": { "type": "number" } }, "required": [ "views", "likes", "comments", "shares", "saves", "engagementRate" ] }, "platformBreakdown": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "contentTypeBreakdown": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "topPosts": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "dailyTrend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "views": { "type": "number" }, "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" }, "viewsGained": { "type": "number" }, "likesGained": { "type": "number" }, "commentsGained": { "type": "number" }, "sharesGained": { "type": "number" } }, "required": [ "date", "views", "likes", "comments", "shares", "viewsGained", "likesGained", "commentsGained", "sharesGained" ] } }, "totalPostsWithAnalytics": { "type": "number" } }, "required": [ "groupId", "groupName", "period", "totals", "platformBreakdown", "contentTypeBreakdown", "topPosts", "dailyTrend", "totalPostsWithAnalytics" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content-groups/{groupId}/analyze": { "post": { "operationId": "analyzeNiche", "summary": "Analyze niche & propose instruction edits", "description": "Run the self-improving loop for a content group: search popular content in its niche, then draft instruction-edit proposals (or auto-apply them if mode/auto_improve is on). Returns a summary + a jobId to poll. Proposals appear at GET /v1/content-groups/{groupId}/instruction-proposals.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group ID" }, "required": true, "description": "Content group ID", "name": "groupId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "propose", "auto" ], "description": "Override the group's auto_improve setting for this run. 'propose' queues edits for approval; 'auto' applies them immediately." }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms to search for niche trends. Defaults to all." }, "limit": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Max popular posts per platform." } } } } } }, "responses": { "202": { "description": "Analysis complete; proposals drafted (or applied).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "jobId": { "type": "string" }, "mode": { "type": "string", "enum": [ "propose", "auto" ] }, "proposalsCount": { "type": "number" }, "appliedCount": { "type": "number", "description": "How many edits were auto-applied (0 in propose mode)." } }, "required": [ "jobId", "mode", "proposalsCount", "appliedCount" ] } }, "required": [ "success", "data" ] } } } } } }, "get": { "operationId": "listNicheAnalysisRuns", "summary": "List niche-analysis runs", "description": "List recent self-improvement runs for a content group (newest first) — including daily auto-improve cron runs. Each run shows its mode, status, and how many edits were proposed/applied, so you can monitor what the automation has done.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group ID" }, "required": true, "description": "Content group ID", "name": "groupId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Max runs (default 20)." }, "required": false, "description": "Max runs (default 20).", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Array of analysis runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "complete", "error" ] }, "progress": { "type": "number" }, "message": { "type": [ "string", "null" ] }, "platforms": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "propose", "auto" ] }, "result": { "type": [ "object", "null" ], "additionalProperties": {} }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "status", "progress", "message", "platforms", "mode", "result", "error_message" ], "description": "An async niche-analysis run with progress + result." } } }, "required": [ "jobs" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/accounts/{accountId}/followers": { "get": { "operationId": "getAccountFollowers", "summary": "Follower history for a connected account", "description": "Returns the daily follower-count history for a connected social account, plus the most recent snapshot. History is populated by a daily cron. Useful for tracking growth over time without scraping public profile pages.", "tags": [ "Accounts", "Analytics" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Social account ID" }, "required": true, "description": "Social account ID", "name": "accountId", "in": "path" }, { "schema": { "type": "string", "description": "How many days of history to return. Default 30, clamped to [1, 365]." }, "required": false, "description": "How many days of history to return. Default 30, clamped to [1, 365].", "name": "days", "in": "query" } ], "responses": { "200": { "description": "Follower history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string" }, "followerCount": { "type": [ "number", "null" ] }, "followingCount": { "type": [ "number", "null" ] }, "followersFetchedAt": { "type": [ "string", "null" ], "format": "date-time" }, "history": { "type": "array", "items": { "type": "object", "properties": { "captured_date": { "type": "string", "description": "ISO date (YYYY-MM-DD) of the snapshot" }, "follower_count": { "type": [ "number", "null" ] }, "following_count": { "type": [ "number", "null" ] } }, "required": [ "captured_date", "follower_count", "following_count" ], "description": "A single day in the follower-count history" } } }, "required": [ "accountId", "platform", "followerCount", "followingCount", "followersFetchedAt", "history" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Account not found." } } } }, "/v1/webhooks/deliveries/{id}/redeliver": { "post": { "operationId": "redeliverWebhook", "summary": "Queue a fresh delivery from an existing one", "description": "Create a new delivery attempt that reuses the original payload. The new delivery gets its own UUID — from the receiver's dedup perspective it is a distinct event. Use when the original delivery was lost and you want a fresh attempt that idempotent receivers will process.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "202": { "description": "Redelivery queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "endpoint_id": { "type": "string", "format": "uuid" }, "event": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "next_attempt_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "endpoint_id", "event", "status", "created_at", "next_attempt_at" ] }, "original_delivery_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "required": [ "delivery", "original_delivery_id", "message" ] } }, "required": [ "success", "data" ] } } } } } } }, "/v1/content-groups/{groupId}/analyze/{jobId}": { "get": { "operationId": "getNicheAnalysisJob", "summary": "Poll a niche-analysis job", "description": "Get an analysis job's status, progress, and result. Terminal states: complete, error.", "tags": [ "Content Groups" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Content group ID" }, "required": true, "description": "Content group ID", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "description": "Analysis job ID" }, "required": true, "description": "Analysis job ID", "name": "jobId", "in": "path" } ], "responses": { "200": { "description": "The analysis job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "app_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "complete", "error" ] }, "progress": { "type": "number" }, "message": { "type": [ "string", "null" ] }, "platforms": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "propose", "auto" ] }, "result": { "type": [ "object", "null" ], "additionalProperties": {} }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "app_id", "status", "progress", "message", "platforms", "mode", "result", "error_message" ], "description": "An async niche-analysis run with progress + result." } }, "required": [ "job" ] } }, "required": [ "success", "data" ] } } } } } } } }, "webhooks": {} }