{ "openapi": "3.1.0", "info": { "title": "Publish Kit API", "version": "1.0.0", "description": "Agentic social media platform API. One platform, one API key — create content, generate AI images & videos, upload media, publish to 9+ social platforms (Twitter, LinkedIn, Instagram, Facebook, TikTok, YouTube, Pinterest, Reddit, Threads), and schedule posts programmatically.\n\n## Authentication\n\nAll authenticated endpoints require an API key via:\n- **Header:** `X-API-Key: pk_live_your_key`\n- **Bearer:** `Authorization: Bearer pk_live_your_key`\n\nCreate API keys at [publishkit.io/dashboard](https://publishkit.io/dashboard).\n\n## Credits\n\nOperations consume credits. Key costs:\n| Operation | Credits |\n|---|---|\n| Publish/schedule a post | 1 |\n| AI post (text only) | 2 |\n| AI post + image | 12 |\n| AI image | 8 |\n| AI video (5s) | 70 |\n| Avatar training | 10 |\n| Avatar image | 8 |", "contact": { "email": "support@publishkit.io", "url": "https://publishkit.io/docs" } }, "servers": [ { "url": "https://publishkit.io", "description": "Production" } ], "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key starting with pk_live_" }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Same API key as Bearer token" } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "MISSING_CONTENT", "INVALID_REQUEST", "NO_CONNECTIONS", "INVALID_API_KEY", "INSUFFICIENT_CREDITS", "SCOPE_DENIED", "RATE_LIMITED", "INTERNAL_ERROR" ] } } }, "Post": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "status": { "type": "string", "enum": ["draft", "scheduled", "published", "failed", "partial"] }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "media_urls": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string" } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "post_statuses": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "status": { "type": "string", "enum": ["success", "error"] }, "error_message": { "type": "string", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "platform_post_id": { "type": "string", "nullable": true } } } } } }, "Connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "Twitter", "LinkedIn", "Instagram", "Facebook", "TikTok", "YouTube", "Pinterest", "Reddit", "Threads" ] }, "username": { "type": "string" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Profile": { "type": "object", "description": "Full profile including branding, products, features, and content strategy.", "properties": { "id": { "type": "string", "format": "uuid" }, "profile_type": { "type": "string", "enum": ["brand", "influencer", "personal"] }, "name": { "type": "string" }, "brand_name": { "type": "string" }, "tagline": { "type": "string" }, "description": { "type": "string" }, "bio": { "type": "string" }, "website_url": { "type": "string" }, "industry": { "type": "string" }, "niche": { "type": "string" }, "branding": { "type": "object", "description": "Visual identity — use these for image generation context.", "properties": { "logo_url": { "type": "string", "description": "Public URL of the brand logo" }, "brand_colors": { "type": "object", "description": "Hex color values for the brand palette", "properties": { "primary": { "type": "string", "example": "#3B82F6" }, "secondary": { "type": "string", "example": "#8B5CF6" }, "accent": { "type": "string", "example": "#EC4899" } } }, "brand_voice": { "type": "string", "example": "professional" }, "font_style": { "type": "string", "example": "inter" }, "brand_images": { "type": "array", "description": "Scraped or uploaded brand image URLs (not logo)", "items": { "type": "object", "properties": { "url": { "type": "string" }, "alt": { "type": "string" }, "type": { "type": "string" } } } } } }, "target_audience": { "description": "Audience description — array or string depending on profile type" }, "expertise_areas": { "type": "array", "items": { "type": "string" }, "description": "Influencer/personal brand expertise areas" }, "content_pillars": { "type": "array", "items": { "type": "string" }, "description": "Core content topics / pillars" }, "content_theme": { "type": "object", "description": "AI content style preferences" }, "content_types": { "type": "object", "description": "Which content types are enabled (product updates, tips, promos, etc.)" }, "website_content": { "type": "object", "description": "Intelligence scraped from the brand website — headlines, tone, keywords, imagery" }, "pricing_data": { "type": "object", "description": "Pricing plans / tiers (for SaaS / service businesses)" }, "value_propositions": { "type": "object", "description": "Key value props and differentiators" }, "products": { "type": "array", "description": "Product catalogue — pass image_url values as productImageUrls when generating images.", "items": { "$ref": "#/components/schemas/Product" } }, "features": { "type": "array", "description": "Product features / capabilities", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "benefit": { "type": "string" }, "category": { "type": "string" }, "featured": { "type": "boolean" } } } } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" }, "url": { "type": "string" }, "image_url": { "type": "string" }, "featured": { "type": "boolean" }, "is_active": { "type": "boolean" } } }, "GeneratedContent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "media_type": { "type": "string", "enum": ["image", "video"] }, "media_urls": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": "string" }, "aspect_ratio": { "type": "string" }, "subject_type": { "type": "string", "enum": ["general", "product", "character", "storyboard", "avatar"] }, "source": { "type": "string" }, "ai_model": { "type": "string" }, "credits_used": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "paths": { "/api/external/v1/profile": { "get": { "operationId": "getProfile", "summary": "Get full profile, branding and product catalogue", "description": "Returns the complete profile including brand identity (colors, logo, voice), website intelligence, products, features, value propositions, content strategy, credit balance, and post stats. Use this as the primary context source before calling any AI generation endpoint.", "tags": ["Profile"], "responses": { "200": { "description": "Profile data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "profile": { "$ref": "#/components/schemas/Profile" }, "account": { "type": "object", "properties": { "credits_remaining": { "type": "integer" }, "subscription_tier": { "type": "string", "enum": ["free", "starter", "pro", "business"] } } }, "stats": { "type": "object", "properties": { "total_posts": { "type": "integer" }, "published": { "type": "integer" }, "scheduled": { "type": "integer" }, "failed": { "type": "integer" }, "drafts": { "type": "integer" } } }, "connections_count": { "type": "integer" } } } } } } } } }, "/api/external/v1/connections": { "get": { "operationId": "getConnections", "summary": "List connected social accounts", "description": "Returns all active social platform connections for the profile. Use this to discover available platforms before posting.", "tags": ["Connections"], "parameters": [ { "name": "platform", "in": "query", "required": false, "description": "Filter by platform name", "schema": { "type": "string", "enum": [ "twitter", "x", "linkedin", "instagram", "facebook", "tiktok", "youtube", "pinterest", "reddit", "threads" ] } } ], "responses": { "200": { "description": "List of connections", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "profile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } }, "available_platforms": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/external/v1/post": { "post": { "operationId": "createPost", "summary": "Publish or schedule a post", "description": "Create and immediately publish or schedule a post to one or more social platforms. Supports text, images, videos, platform-specific content, and media file uploads via multipart/form-data. Cost: 1 credit per post.", "tags": ["Posts"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["content"], "properties": { "content": { "type": "string", "description": "Post text content" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "twitter", "x", "linkedin", "instagram", "facebook", "tiktok", "youtube", "pinterest", "reddit", "threads" ] }, "description": "Platform names to post to. Uses all active connections for each platform." }, "connectionIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Specific connection UUIDs to post to (alternative to platforms)" }, "mediaUrls": { "type": "array", "items": { "type": "string" }, "description": "URLs of already-uploaded media files" }, "thumbnailUrl": { "type": "string", "description": "Thumbnail image URL for video posts" }, "platformContent": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Per-platform content overrides. Keys are platform names, values are text." }, "scheduledAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date to schedule. Omit to publish immediately." }, "hashtags": { "type": "array", "items": { "type": "string" }, "description": "Hashtags to append" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": ["content"], "properties": { "content": { "type": "string" }, "platforms": { "type": "string", "description": "Comma-separated platform names" }, "connectionIds": { "type": "string", "description": "Comma-separated connection UUIDs" }, "media": { "type": "string", "format": "binary", "description": "Media files (image/video). Max 200MB each. Types: JPEG, PNG, GIF, WebP, MP4, QuickTime, WebM." }, "thumbnail": { "type": "string", "format": "binary", "description": "Thumbnail image for video posts" }, "mediaUrls": { "type": "string", "description": "Comma-separated existing media URLs" }, "thumbnailUrl": { "type": "string" }, "platformContent": { "type": "string", "description": "JSON string of platform content overrides" }, "scheduledAt": { "type": "string", "format": "date-time" }, "hashtags": { "type": "string", "description": "Comma-separated hashtags" } } } } } }, "responses": { "200": { "description": "Post published or scheduled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "post": { "$ref": "#/components/schemas/Post" }, "results": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string" }, "success": { "type": "boolean" }, "postId": { "type": "string" }, "error": { "type": "string" } } } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } } }, "credits_remaining": { "type": "integer" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getPosts", "summary": "Get post history", "description": "Retrieve paginated post history with optional status filtering. Returns posts with platform-level publishing details.", "tags": ["Posts"], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 }, "description": "Results per page" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["published", "scheduled", "failed", "draft", "partial"] }, "description": "Filter by status" } ], "responses": { "200": { "description": "Paginated posts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } } } } }, "/api/content/posts/generate": { "post": { "operationId": "generatePost", "summary": "Generate AI social media post", "description": "Generate AI-written social media post with optional AI image. Uses profile brand context, products, and audience. Cost: 2 credits text-only, 12 credits with image.", "tags": ["AI Content"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["profileId"], "properties": { "profileId": { "type": "string", "format": "uuid", "description": "Profile UUID for brand context" }, "postType": { "type": "string", "enum": [ "productUpdates", "educational", "promotional", "engagement" ], "description": "Content style" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Target platforms for tone/style" }, "includeImage": { "type": "boolean", "description": "Generate AI image (+10 credits)" }, "customPrompt": { "type": "string", "description": "Custom instructions for the AI" }, "postCount": { "type": "integer", "default": 1, "description": "Number of posts to generate" }, "product": { "type": "object", "description": "Product data for product-focused content" } } } } } }, "responses": { "200": { "description": "Generated post content" } } } }, "/api/ai-content/images/generate": { "post": { "operationId": "generateImage", "summary": "Generate AI image", "description": "Generate an AI image for social media. Supports product photography, brand visuals, templates, and style references. Cost: 8 credits.", "tags": ["AI Images"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["prompt", "profileId"], "properties": { "prompt": { "type": "string", "description": "Image generation prompt", "example": "A minimalist product shot of a skincare serum bottle on a marble surface with soft natural lighting" }, "aspectRatio": { "type": "string", "enum": ["1:1", "16:9", "9:16", "4:3", "3:4"], "description": "Image aspect ratio", "example": "1:1" }, "profileId": { "type": "string", "format": "uuid", "description": "Your profile UUID (get it from GET /api/external/v1/profile)", "example": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }, "subjectType": { "type": "string", "enum": ["general", "product"], "example": "general" }, "productImageUrls": { "type": "array", "description": "Optional product image URLs to use as visual references. Omit or leave empty if not needed.", "items": { "type": "string", "format": "uri" }, "example": [] }, "styleReferenceUrls": { "type": "array", "description": "Optional style reference image URLs. Omit or leave empty if not needed.", "items": { "type": "string", "format": "uri" }, "example": [] }, "useBrandContext": { "type": "boolean", "description": "Include profile brand colors in the prompt", "default": true, "example": true } } }, "example": { "prompt": "A minimalist product shot of a skincare serum bottle on a marble surface with soft natural lighting", "aspectRatio": "1:1", "profileId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "subjectType": "general", "productImageUrls": [], "styleReferenceUrls": [], "useBrandContext": true } } } }, "responses": { "200": { "description": "Generated image", "content": { "application/json": { "schema": { "type": "object", "properties": { "imageUrl": { "type": "string" }, "generationId": { "type": "string" } } } } } } } } }, "/api/ai-content/avatars/generate": { "post": { "operationId": "generateAvatarImage", "summary": "Generate image with trained avatar", "description": "Generate an image using a trained avatar. Pass products or scene images via additionalImages to create avatar + product compositions.", "tags": ["AI Avatars"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["avatarId", "prompt", "profileId"], "properties": { "avatarId": { "type": "string", "description": "Trained avatar ID (must be ready)" }, "prompt": { "type": "string", "description": "Scene/style description" }, "profileId": { "type": "string", "format": "uuid" }, "aspectRatio": { "type": "string" }, "numOutputs": { "type": "integer", "default": 1 } } } } } }, "responses": { "200": { "description": "Generated avatar images" } } } }, "/api/ai-content/avatars/list": { "get": { "operationId": "listAvatars", "summary": "List all avatars", "description": "Get all trained avatars for the profile.", "tags": ["AI Avatars"], "responses": { "200": { "description": "List of avatars" } } } }, "/api/media/upload": { "post": { "operationId": "uploadMedia", "summary": "Upload media file", "description": "Upload video/image files. Returns public URLs for use in posts.", "tags": ["Media"], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "video": { "type": "string", "format": "binary" }, "thumbnail": { "type": "string", "format": "binary" }, "duration": { "type": "number" }, "profileId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Upload successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "videoUrl": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "duration": { "type": "number" }, "size": { "type": "integer" } } } } } } } } }, "/api/tools/bio-generator": { "post": { "operationId": "generateBio", "summary": "Generate platform-specific bios (free, no auth)", "description": "Generate bios for social media profiles. No API key required. Rate limited to 15 requests/minute.", "tags": ["Free Tools"], "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "twitter", "linkedin", "instagram", "facebook", "tiktok", "pinterest", "youtube", "reddit", "custom" ] }, "name": { "type": "string" }, "niche": { "type": "string" }, "keywords": { "type": "string" }, "tone": { "type": "string", "enum": ["professional", "casual", "witty", "inspiring"] }, "includeEmojis": { "type": "boolean" }, "count": { "type": "integer", "default": 3 } } } } } }, "responses": { "200": { "description": "Generated bios", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "bios": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/tools/caption-generator": { "post": { "operationId": "generateCaption", "summary": "Generate social media captions", "description": "Generate platform-optimized captions. No API key required. Rate limited to 15 requests/minute.", "tags": ["Free Tools"], "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "Topic or subject for the caption" }, "platform": { "type": "string", "enum": [ "twitter", "instagram", "linkedin", "facebook", "tiktok" ] }, "tone": { "type": "string", "enum": [ "professional", "casual", "witty", "inspiring", "educational" ] }, "includeHashtags": { "type": "boolean" }, "count": { "type": "integer", "default": 3 } } } } } }, "responses": { "200": { "description": "Generated captions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "captions": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/tools/hashtag-generator": { "post": { "operationId": "generateHashtags", "summary": "Generate hashtags", "description": "Generate relevant hashtags for a topic or content. No API key required. Rate limited to 15 requests/minute.", "tags": ["Free Tools"], "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "Topic or content description" }, "platform": { "type": "string", "enum": ["instagram", "twitter", "tiktok", "linkedin"] }, "count": { "type": "integer", "default": 15 } } } } } }, "responses": { "200": { "description": "Generated hashtags", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "hashtags": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/ai-content/videos/generate": { "post": { "operationId": "generateVideoFromImage", "summary": "Generate video from image + prompt", "description": "Animate an image into a video using a motion prompt. Cost: 70 credits per 5 seconds.", "tags": ["AI Videos"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["imageUrl", "profileId"], "properties": { "imageUrl": { "type": "string", "description": "Source image URL to animate" }, "prompt": { "type": "string", "description": "Motion/animation prompt" }, "profileId": { "type": "string", "format": "uuid" }, "duration": { "type": "integer", "default": 5, "description": "Video duration in seconds" } } } } } }, "responses": { "200": { "description": "Generated video", "content": { "application/json": { "schema": { "type": "object", "properties": { "videoUrl": { "type": "string" }, "generationId": { "type": "string" } } } } } } } } }, "/api/ai-content/videos/subtitles": { "post": { "operationId": "addSubtitles", "summary": "Add subtitles to video", "description": "Auto-generate and burn subtitles into a video. Cost: 5 credits.", "tags": ["AI Videos"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["videoUrl", "profileId"], "properties": { "videoUrl": { "type": "string" }, "profileId": { "type": "string", "format": "uuid" }, "language": { "type": "string", "default": "en" }, "style": { "type": "string", "enum": ["minimal", "bold", "outlined"] } } } } } }, "responses": { "200": { "description": "Video with subtitles", "content": { "application/json": { "schema": { "type": "object", "properties": { "videoUrl": { "type": "string" } } } } } } } } }, "/api/ai-content/avatars/update": { "patch": { "operationId": "updateAvatar", "summary": "Update avatar details", "description": "Update an avatar's name or description.", "tags": ["AI Avatars"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["avatarId"], "properties": { "avatarId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated avatar" } } } }, "/api/ai-content/avatars/delete": { "delete": { "operationId": "deleteAvatar", "summary": "Delete an avatar", "description": "Permanently delete a trained avatar and all associated data.", "tags": ["AI Avatars"], "parameters": [ { "name": "avatarId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Avatar deleted" } } } }, "/api/ai-content/avatars/set-default": { "post": { "operationId": "setDefaultAvatar", "summary": "Set default avatar for profile", "description": "Mark an avatar as the default for AI content generation.", "tags": ["AI Avatars"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["avatarId", "profileId"], "properties": { "avatarId": { "type": "string" }, "profileId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Default avatar updated" } } } }, "/api/ai-content/avatars/voices": { "get": { "operationId": "listAvatarVoices", "summary": "List available voices for avatars", "description": "Get all available voice options that can be assigned to avatars.", "tags": ["AI Avatars"], "responses": { "200": { "description": "List of voices", "content": { "application/json": { "schema": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "gender": { "type": "string" }, "preview_url": { "type": "string" } } } } } } } } } } } }, "/api/profiles/{profileId}/products": { "get": { "operationId": "listProducts", "summary": "List all products", "description": "Get all products for a profile. Products are used as context for AI content generation.", "tags": ["Products"], "parameters": [ { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Products list", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } } } } }, "post": { "operationId": "createProduct", "summary": "Create a product", "description": "Add a new product to the profile. Products can be used for AI-generated product posts and images.", "tags": ["Products"], "parameters": [ { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string", "default": "USD" }, "url": { "type": "string", "description": "Product page URL" }, "image": { "type": "string", "description": "Product image URL" }, "sku": { "type": "string" }, "featured": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Created product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } } } }, "patch": { "operationId": "bulkUpdateProducts", "summary": "Bulk update/delete products", "description": "Upsert an array of products. Products included are created or updated; products not in the array are deleted.", "tags": ["Products"], "parameters": [ { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } } }, "responses": { "200": { "description": "Products updated" } } } }, "/api/profiles/{profileId}/generated-content": { "get": { "operationId": "listGeneratedContent", "summary": "Browse AI-generated content library", "description": "Retrieve all AI-generated images and videos for a profile. Useful for agents to reuse generated media in new posts.", "tags": ["Generated Content Library"], "parameters": [ { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 12 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "media_type", "in": "query", "schema": { "type": "string", "enum": ["image", "video", "all"], "default": "all" } }, { "name": "subject_type", "in": "query", "schema": { "type": "string", "enum": [ "general", "product", "character", "storyboard", "avatar", "all" ], "default": "all" } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": ["ai-image", "ai-video", "avatar", "all"], "default": "all" } }, { "name": "is_favorite", "in": "query", "schema": { "type": "string", "enum": ["true", "false", "all"], "default": "all" } } ], "responses": { "200": { "description": "Generated content", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedContent" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" } } } } } } } } }, "/api/profiles/{profileId}/upload-media": { "post": { "operationId": "getSignedUploadUrl", "summary": "Get signed upload URL for media", "description": "Generate a signed URL for direct browser-side media upload to cloud storage. Client uploads directly to the signed URL, then uses the public URL in posts.", "tags": ["Media"], "parameters": [ { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["fileName"], "properties": { "fileName": { "type": "string" }, "contentType": { "type": "string", "description": "MIME type, e.g. image/jpeg" } } } } } }, "responses": { "200": { "description": "Signed upload URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadUrl": { "type": "string", "description": "PUT to this URL to upload the file" }, "publicUrl": { "type": "string", "description": "Use this URL in posts after uploading" }, "token": { "type": "string" }, "path": { "type": "string" } } } } } } } } }, "/api/profiles/{profileId}/upload-media-url": { "post": { "operationId": "uploadMediaFromUrl", "summary": "Upload media from external URL", "description": "Download an image from an external URL and upload it to cloud storage. Returns a permanent public URL.", "tags": ["Media"], "parameters": [ { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["imageUrl"], "properties": { "imageUrl": { "type": "string", "description": "External image URL to download and re-upload" } } } } } }, "responses": { "200": { "description": "Uploaded media", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "url": { "type": "string" }, "filePath": { "type": "string" }, "size": { "type": "integer" } } } } } } } } }, "/api/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "description": "Get all API keys for the authenticated user, optionally filtered by profile.", "tags": ["API Keys"], "parameters": [ { "name": "profile_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "API keys", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key_prefix": { "type": "string", "description": "First characters of the key (e.g. pk_live_abc...)" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit": { "type": "integer" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "usage_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "post": { "operationId": "createApiKey", "summary": "Create API key", "description": "Create a new API key scoped to a profile. The full key is only returned once — store it immediately.", "tags": ["API Keys"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "profile_id"], "properties": { "name": { "type": "string", "description": "Human-readable name for this key" }, "profile_id": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "post:create", "post:read", "connection:read", "connection:write", "profile:read", "account:read" ] }, "default": ["post:create", "post:read", "connection:read"] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "rate_limit": { "type": "integer", "default": 100, "description": "Max requests per hour" } } } } } }, "responses": { "200": { "description": "Created API key — full key shown only once", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string", "description": "Full API key — pk_live_... — store this now, it will not be shown again" }, "key_prefix": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "patch": { "operationId": "updateApiKey", "summary": "Update API key", "description": "Update an API key's name, active status, scopes, rate limit, or expiration.", "tags": ["API Keys"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "responses": { "200": { "description": "Updated API key" } } }, "delete": { "operationId": "deleteApiKey", "summary": "Delete API key", "description": "Permanently delete an API key. All requests using this key will immediately fail.", "tags": ["API Keys"], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key deleted" } } } }, "/api/user": { "get": { "operationId": "getUser", "summary": "Get current user", "description": "Returns the authenticated user's account data including credits and subscription details.", "tags": ["Account"], "responses": { "200": { "description": "User data", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "credits": { "type": "integer" }, "credits_used_this_period": { "type": "integer" }, "subscription_tier": { "type": "string" }, "subscription_status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/user/credits": { "get": { "operationId": "getCredits", "summary": "Get credit balance", "description": "Returns the user's current credit balance, usage this period, and subscription details.", "tags": ["Account"], "responses": { "200": { "description": "Credit balance and subscription", "content": { "application/json": { "schema": { "type": "object", "properties": { "credits": { "type": "integer" }, "creditsUsedThisPeriod": { "type": "integer" }, "subscription": { "type": "object", "properties": { "tier": { "type": "string" }, "status": { "type": "string" }, "displayName": { "type": "string" }, "creditsMonthly": { "type": "integer" }, "priceMonthly": { "type": "number" }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" } } } } } } } } } } }, "/api/subscription/plans": { "get": { "operationId": "getSubscriptionPlans", "summary": "Get subscription plans", "description": "Returns all available subscription plans with pricing, credit allocations, and features.", "tags": ["Account"], "security": [], "responses": { "200": { "description": "Subscription plans", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tier": { "type": "string" }, "price_monthly": { "type": "number" }, "price_yearly": { "type": "number" }, "credits_monthly": { "type": "integer" }, "max_profiles": { "type": "integer" }, "features": { "type": "array", "items": { "type": "string" } }, "is_popular": { "type": "boolean" } } } } } } } } } } }, "tags": [ { "name": "Profile", "description": "Profile and account information" }, { "name": "Connections", "description": "Social platform connections" }, { "name": "Posts", "description": "Create, publish, schedule, and retrieve posts" }, { "name": "AI Content", "description": "AI-powered post text generation" }, { "name": "AI Images", "description": "AI image generation, editing, and enhancement" }, { "name": "AI Videos", "description": "AI video generation from images, prompts, and storyboards" }, { "name": "AI Avatars", "description": "Train AI avatars and generate avatar images & videos" }, { "name": "Media", "description": "Media file upload and URL-based upload" }, { "name": "Products", "description": "Product catalog for AI content context" }, { "name": "Generated Content Library", "description": "Browse and reuse AI-generated images and videos" }, { "name": "API Keys", "description": "Create and manage API keys" }, { "name": "Account", "description": "User account, credits, and subscription" }, { "name": "Free Tools", "description": "Free public tools — no API key required" } ] }