{ "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/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/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", "failed" ], "description": "Post lifecycle status" }, "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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", "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/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" ] }, "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/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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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" ], "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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" ], "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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" ], "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/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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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", "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, carousel, and video post types. Media URLs must be publicly accessible.", "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", "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", "format": "uri", "description": "Required for postType=image" }, "imageUrls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Required for postType=carousel" }, "videoUrl": { "type": "string", "format": "uri", "description": "Required for postType=video" }, "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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", "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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", "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "required": [ "success", "data" ] } } } } } }, "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/generate": { "post": { "operationId": "generateImage", "summary": "Generate an image", "description": "Generate an AI image via Gemini Flash (default), GPT Image 1.5, 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/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/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/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/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" } } }, "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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" ], "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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" ], "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" }, "minItems": 1 } }, "required": [ "platforms" ] } } } }, "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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" ], "description": "A video post record" } }, "required": [ "video" ] } }, "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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", "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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", "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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", "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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", "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}/images": { "put": { "operationId": "updatePostImages", "summary": "Update post images", "description": "Attach, replace, or remove images on a post.", "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", "failed" ], "description": "Post lifecycle status" }, "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" ] }, "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", "is_manual" ], "description": "A social media post record" } }, "required": [ "post" ] } }, "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/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" } ], "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", "additionalProperties": {} } }, "totalPostsWithAnalytics": { "type": "number" } }, "required": [ "groupId", "groupName", "period", "totals", "platformBreakdown", "contentTypeBreakdown", "topPosts", "dailyTrend", "totalPostsWithAnalytics" ] } }, "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" ] } } } } } } } }, "webhooks": {} }