{ "openapi": "3.0.1", "info": { "title": "Upload-Post API", "description": "Upload-Post is a unified social media API that allows you to upload videos, photos, text, and documents to 10+ social media platforms (TikTok, Instagram, LinkedIn, YouTube, Facebook, X/Twitter, Threads, Pinterest, Bluesky, Reddit, Discord, Telegram) with a single API call. Features include scheduling, queue system, async uploads, FFmpeg media processing, analytics, webhooks, and white-label user management.", "version": "1.0.0", "contact": { "name": "Upload-Post Support", "url": "https://upload-post.com" }, "license": { "name": "Proprietary", "url": "https://upload-post.com/terms" } }, "servers": [ { "url": "https://api.upload-post.com/api", "description": "Production server" } ], "tags": [ { "name": "Content Upload", "description": "Upload video, photo, text, and document content to social media platforms." }, { "name": "Upload Management", "description": "Check upload status, view history, and manage scheduled posts." }, { "name": "Queue System", "description": "Configure and preview the automatic post queue." }, { "name": "Platform Integration", "description": "Retrieve platform-specific data: Facebook pages, LinkedIn pages, Pinterest boards, Reddit posts, and analytics." }, { "name": "User Management", "description": "Create, list, get, and delete user profiles." }, { "name": "Authentication", "description": "Verify API keys, generate and validate JWT tokens for white-label integration." }, { "name": "FFmpeg Editor", "description": "Process and transform media using FFmpeg commands on Upload-Post infrastructure." }, { "name": "Webhooks", "description": "Configure real-time webhook and Telegram notifications for upload events." }, { "name": "Instagram Interactions", "description": "Retrieve Instagram media, comments, conversations, and send direct messages or private replies." } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/upload": { "post": { "operationId": "uploadVideo", "summary": "Upload video", "description": "Upload a video to one or more social media platforms. Supports TikTok, Instagram, LinkedIn, YouTube, Facebook, X (Twitter), Threads, Pinterest, Bluesky, Reddit, Discord, and Telegram. Supports immediate, async, scheduled, and queued uploads.", "tags": ["Content Upload"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["user", "platform[]", "video"], "properties": { "user": { "type": "string", "description": "User profile identifier." }, "platform[]": { "type": "array", "items": { "$ref": "#/components/schemas/VideoPlatformEnum" }, "description": "Platform(s) to upload to." }, "video": { "type": "string", "format": "binary", "description": "The video file to upload (binary file) or a public video URL." }, "title": { "type": "string", "description": "Default title/caption of the video. Required for YouTube and Reddit; optional for all other platforms. Platform-specific titles override this." }, "description": { "type": "string", "description": "Optional extended text used on LinkedIn commentary, Facebook descriptions, YouTube descriptions, and Pinterest notes. Ignored elsewhere." }, "scheduled_date": { "type": "string", "format": "date-time", "description": "ISO-8601 date/time to schedule publishing (e.g., '2025-12-31T23:45:00Z'). Must be in the future (≤365 days). Omit for immediate upload. Cannot be used with `add_to_queue`." }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g., 'Europe/Madrid', 'America/New_York'). If provided, `scheduled_date` is interpreted in this timezone. Defaults to UTC." }, "async_upload": { "type": "boolean", "description": "If true, returns immediately with a `request_id` and processes in the background. If false but upload takes >59s, automatically switches to async.", "default": false }, "add_to_queue": { "type": "boolean", "description": "If true, automatically schedules the post to the next available queue slot. Cannot be used with `scheduled_date`.", "default": false }, "first_comment": { "type": "string", "description": "Automatically post a first comment after publishing. Supported on Instagram, Facebook, Threads, Bluesky, Reddit, X, YouTube, and LinkedIn." }, "instagram_first_comment": { "type": "string", "description": "[Instagram] Platform-specific first comment. Overrides `first_comment`." }, "facebook_first_comment": { "type": "string", "description": "[Facebook] Platform-specific first comment. Overrides `first_comment`." }, "x_first_comment": { "type": "string", "description": "[X] Platform-specific first comment. Overrides `first_comment`." }, "threads_first_comment": { "type": "string", "description": "[Threads] Platform-specific first comment. Overrides `first_comment`." }, "youtube_first_comment": { "type": "string", "description": "[YouTube] Platform-specific first comment. Overrides `first_comment`." }, "reddit_first_comment": { "type": "string", "description": "[Reddit] Platform-specific first comment. Overrides `first_comment`." }, "bluesky_first_comment": { "type": "string", "description": "[Bluesky] Platform-specific first comment. Overrides `first_comment`." }, "linkedin_first_comment": { "type": "string", "description": "[LinkedIn] Platform-specific first comment. Overrides `first_comment`." }, "first_comment_media[]": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Image files to attach to the first comment as inline images. Currently supported on Reddit. Not available for scheduled or queued posts." }, "instagram_title": { "type": "string", "description": "[Instagram] Specific title. Fallbacks to `title`." }, "facebook_title": { "type": "string", "description": "[Facebook] Specific title. Fallbacks to `title`. Ignored if facebook_media_type is STORIES." }, "tiktok_title": { "type": "string", "description": "[TikTok] Specific title. Fallbacks to `title`." }, "linkedin_title": { "type": "string", "description": "[LinkedIn] Specific title. Fallbacks to `title`." }, "x_title": { "type": "string", "description": "[X] Specific title. Fallbacks to `title`." }, "youtube_title": { "type": "string", "description": "[YouTube] Specific title. Fallbacks to `title`." }, "pinterest_title": { "type": "string", "description": "[Pinterest] Specific title. Fallbacks to `title`." }, "threads_title": { "type": "string", "description": "[Threads] Specific title. Fallbacks to `title`." }, "threads_topic_tag": { "type": "string", "description": "[Threads] A topic tag for the post (1-50 characters). Cannot contain periods (.) or ampersands (&). One tag per post.", "maxLength": 50 }, "bluesky_title": { "type": "string", "description": "[Bluesky] Specific text. Fallbacks to `title`." }, "reddit_title": { "type": "string", "description": "[Reddit] Specific title. Fallbacks to `title`." }, "privacy_level": { "$ref": "#/components/schemas/TikTokPrivacyLevel" }, "disable_duet": { "type": "boolean", "description": "[TikTok] Disable duet feature.", "default": false }, "disable_comment": { "type": "boolean", "description": "[TikTok] Disable comments.", "default": false }, "disable_stitch": { "type": "boolean", "description": "[TikTok] Disable stitch feature.", "default": false }, "post_mode": { "$ref": "#/components/schemas/TikTokPostMode" }, "cover_timestamp": { "type": "integer", "description": "[TikTok] Timestamp in milliseconds for video cover.", "default": 1000 }, "brand_content_toggle": { "type": "boolean", "description": "[TikTok] Set to true for paid partnerships promoting third-party brands.", "default": false }, "brand_organic_toggle": { "type": "boolean", "description": "[TikTok] Set to true when promoting the creator's own business.", "default": false }, "is_aigc": { "type": "boolean", "description": "[TikTok] Indicates if content is AI-generated.", "default": false }, "media_type": { "$ref": "#/components/schemas/InstagramVideoMediaType" }, "share_mode": { "$ref": "#/components/schemas/InstagramShareMode" }, "share_to_feed": { "type": "boolean", "description": "[Instagram] Whether to share to feed (only for regular Reels, not Trial Reels).", "default": true }, "collaborators": { "type": "string", "description": "[Instagram] Comma-separated list of collaborator usernames. Not available for Trial Reels." }, "cover_url": { "type": "string", "description": "[Instagram] URL for custom video cover. Alternative to cover_image binary upload." }, "cover_image": { "type": "string", "format": "binary", "description": "[Instagram] Binary cover image for Reels (JPEG, max 8MB). If both cover_image and cover_url are provided, cover_url takes precedence." }, "audio_name": { "type": "string", "description": "[Instagram] Name of the audio track embedded in your video (Reels only)." }, "user_tags": { "type": "string", "description": "[Instagram] Comma-separated list of user tags." }, "location_id": { "type": "string", "description": "[Instagram] Instagram location ID." }, "thumb_offset": { "type": "string", "description": "[Instagram] Timestamp offset for video thumbnail." }, "linkedin_description": { "type": "string", "description": "[LinkedIn] Sent as the LinkedIn commentary. If omitted, reuses `title`." }, "visibility": { "$ref": "#/components/schemas/LinkedInVisibility" }, "target_linkedin_page_id": { "type": "string", "description": "[LinkedIn] LinkedIn page ID to upload to an organization page." }, "youtube_description": { "type": "string", "description": "[YouTube] Populates snippet.description. If omitted, uses `title`." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "[YouTube] Array of video tags." }, "categoryId": { "type": "string", "description": "[YouTube] Video category ID.", "default": "22" }, "privacyStatus": { "$ref": "#/components/schemas/YouTubePrivacyStatus" }, "embeddable": { "type": "boolean", "description": "[YouTube] Whether video is embeddable.", "default": true }, "license": { "type": "string", "description": "[YouTube] Video license ('youtube' or 'creativeCommon').", "default": "youtube", "enum": ["youtube", "creativeCommon"] }, "publicStatsViewable": { "type": "boolean", "description": "[YouTube] Whether public stats are viewable.", "default": true }, "thumbnail": { "type": "string", "format": "binary", "description": "[YouTube] Custom thumbnail image file (JPG/PNG/GIF/BMP, max 2MB). Not supported for Shorts." }, "thumbnail_url": { "type": "string", "format": "uri", "description": "[YouTube] Alternative: provide thumbnail as a public URL." }, "selfDeclaredMadeForKids": { "type": "boolean", "description": "[YouTube] Explicit declaration for COPPA compliance.", "default": false }, "containsSyntheticMedia": { "type": "boolean", "description": "[YouTube] Declaration that video contains AI-generated content.", "default": false }, "defaultLanguage": { "type": "string", "description": "[YouTube] Language of title and description (BCP-47 code, e.g., 'es', 'en')." }, "defaultAudioLanguage": { "type": "string", "description": "[YouTube] Language of the video audio (BCP-47 code, e.g., 'es-ES', 'en-US')." }, "allowedCountries": { "type": "string", "description": "[YouTube] Comma-separated ISO 3166-1 alpha-2 country codes where the video is allowed. Cannot be used with `blockedCountries`." }, "blockedCountries": { "type": "string", "description": "[YouTube] Comma-separated ISO 3166-1 alpha-2 country codes where the video is blocked. Cannot be used with `allowedCountries`." }, "hasPaidProductPlacement": { "type": "boolean", "description": "[YouTube] Declaration of paid product placements for FTC compliance.", "default": false }, "recordingDate": { "type": "string", "format": "date-time", "description": "[YouTube] Recording date (ISO 8601, e.g., '2024-01-15T14:30:00Z')." }, "facebook_page_id": { "type": "string", "description": "[Facebook] Facebook Page ID where the video will be posted. Required for Facebook. Auto-detected if only one page is connected." }, "facebook_description": { "type": "string", "description": "[Facebook] Sent as video description. Ignored for STORIES." }, "facebook_media_type": { "$ref": "#/components/schemas/FacebookVideoMediaType" }, "video_state": { "type": "string", "description": "[Facebook] Desired state of the video.", "default": "PUBLISHED", "enum": ["DRAFT", "PUBLISHED"] }, "x_long_text_as_post": { "type": "boolean", "description": "[X] When true, publishes long text as a single post instead of a thread.", "default": false }, "reply_settings": { "$ref": "#/components/schemas/XReplySettings" }, "geo_place_id": { "type": "string", "description": "[X] Place ID for geographic location." }, "nullcast": { "type": "boolean", "description": "[X] Whether to publish without broadcasting (promoted-only posts).", "default": false }, "for_super_followers_only": { "type": "boolean", "description": "[X] Tweet exclusive for super followers.", "default": false }, "community_id": { "type": "string", "description": "[X] Community ID for posting to specific communities." }, "share_with_followers": { "type": "boolean", "description": "[X] Share community post with followers.", "default": false }, "direct_message_deep_link": { "type": "string", "description": "[X] Link to take conversation to private Direct Message." }, "tagged_user_ids": { "type": "array", "items": { "type": "string" }, "description": "[X] Array of user IDs to tag in the media (max 10)." }, "reply_to_id": { "type": "string", "description": "[X] ID of the tweet to reply to." }, "exclude_reply_user_ids": { "type": "array", "items": { "type": "string" }, "description": "[X] User IDs to exclude from replying. Requires `reply_to_id`." }, "pinterest_description": { "type": "string", "description": "[Pinterest] Pin description. If omitted, reuses `title`." }, "pinterest_board_id": { "type": "string", "description": "[Pinterest] Pinterest board ID to publish to. Required when platform includes pinterest." }, "pinterest_alt_text": { "type": "string", "description": "[Pinterest] Alt text for the video." }, "pinterest_link": { "type": "string", "description": "[Pinterest] Destination link for the video Pin." }, "pinterest_cover_image_url": { "type": "string", "description": "[Pinterest] URL of an image to use as the video cover." }, "pinterest_cover_image_content_type": { "type": "string", "description": "[Pinterest] Content type of the cover image (e.g., image/jpeg)." }, "pinterest_cover_image_data": { "type": "string", "description": "[Pinterest] Base64 encoded cover image data." }, "pinterest_cover_image_key_frame_time": { "type": "integer", "description": "[Pinterest] Time in milliseconds of the video frame to use as cover." }, "subreddit": { "type": "string", "description": "[Reddit] Name of the subreddit (without 'r/'). Required when platform includes reddit." }, "flair_id": { "type": "string", "description": "[Reddit] ID of the flair to apply to the post." } } } } } }, "responses": { "200": { "description": "Upload completed synchronously or async processing started.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SyncUploadResponse" }, { "$ref": "#/components/schemas/AsyncUploadResponse" } ] } } } }, "202": { "description": "Post scheduled or queued successfully.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ScheduledUploadResponse" }, { "$ref": "#/components/schemas/QueuedUploadResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/upload_photos": { "post": { "operationId": "uploadPhotos", "summary": "Upload photos", "description": "Upload photos (and mixed media for Instagram/Threads carousels) to social media platforms. Supports TikTok, Instagram, LinkedIn, Facebook, X (Twitter), Threads, Pinterest, Bluesky, Reddit, Discord, and Telegram.", "tags": ["Content Upload"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["user", "platform[]", "photos[]"], "properties": { "user": { "type": "string", "description": "User profile identifier." }, "platform[]": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoPlatformEnum" }, "description": "Platform(s) to upload to." }, "photos[]": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Array of photo files. Instagram & Threads also accept videos for mixed carousels." }, "title": { "type": "string", "description": "Default title/caption. Required for Reddit; optional for all other platforms. Platform-specific titles override this." }, "description": { "type": "string", "description": "Optional extended text used on TikTok photo descriptions, LinkedIn commentary, Facebook descriptions, Pinterest notes, and Reddit bodies. Ignored elsewhere." }, "scheduled_date": { "type": "string", "format": "date-time", "description": "ISO-8601 date/time to schedule publishing. Must be in the future (≤365 days). Cannot be used with `add_to_queue`." }, "timezone": { "type": "string", "description": "IANA timezone identifier. Defaults to UTC." }, "async_upload": { "type": "boolean", "description": "If true, returns immediately with a `request_id`.", "default": false }, "add_to_queue": { "type": "boolean", "description": "If true, schedules to next available queue slot. Cannot be used with `scheduled_date`.", "default": false }, "first_comment": { "type": "string", "description": "Automatically post a first comment after publishing." }, "instagram_first_comment": { "type": "string", "description": "[Instagram] Platform-specific first comment." }, "facebook_first_comment": { "type": "string", "description": "[Facebook] Platform-specific first comment." }, "x_first_comment": { "type": "string", "description": "[X] Platform-specific first comment." }, "threads_first_comment": { "type": "string", "description": "[Threads] Platform-specific first comment." }, "reddit_first_comment": { "type": "string", "description": "[Reddit] Platform-specific first comment." }, "bluesky_first_comment": { "type": "string", "description": "[Bluesky] Platform-specific first comment." }, "first_comment_media[]": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "One or more image files to attach to the first comment. Currently supported on Reddit. Not available for scheduled or queued posts." }, "instagram_title": { "type": "string", "description": "[Instagram] Specific title." }, "facebook_title": { "type": "string", "description": "[Facebook] Specific title." }, "tiktok_title": { "type": "string", "description": "[TikTok] Specific title." }, "linkedin_title": { "type": "string", "description": "[LinkedIn] Specific title." }, "x_title": { "type": "string", "description": "[X] Specific title." }, "pinterest_title": { "type": "string", "description": "[Pinterest] Specific title." }, "threads_title": { "type": "string", "description": "[Threads] Specific title." }, "threads_topic_tag": { "type": "string", "description": "[Threads] A topic tag for the post (1-50 characters). Cannot contain periods (.) or ampersands (&). One tag per post.", "maxLength": 50 }, "bluesky_title": { "type": "string", "description": "[Bluesky] Specific text." }, "reddit_title": { "type": "string", "description": "[Reddit] Specific title." }, "linkedin_description": { "type": "string", "description": "[LinkedIn] Post commentary." }, "visibility": { "type": "string", "description": "[LinkedIn] Visibility setting.", "default": "PUBLIC", "enum": ["PUBLIC"] }, "target_linkedin_page_id": { "type": "string", "description": "[LinkedIn] LinkedIn page ID to upload to an organization." }, "facebook_page_id": { "type": "string", "description": "[Facebook] Facebook Page ID. Required when platform includes facebook. Auto-detected if only one page is connected." }, "facebook_media_type": { "$ref": "#/components/schemas/FacebookPhotoMediaType" }, "x_long_text_as_post": { "type": "boolean", "description": "[X] When true, publishes long text as a single post.", "default": false }, "reply_settings": { "$ref": "#/components/schemas/XReplySettings" }, "geo_place_id": { "type": "string", "description": "[X] Place ID for geographic location." }, "nullcast": { "type": "boolean", "description": "[X] Publish without broadcasting.", "default": false }, "for_super_followers_only": { "type": "boolean", "description": "[X] Exclusive for super followers.", "default": false }, "community_id": { "type": "string", "description": "[X] Community ID." }, "share_with_followers": { "type": "boolean", "description": "[X] Share community post with followers.", "default": false }, "direct_message_deep_link": { "type": "string", "description": "[X] Direct Message deep link." }, "tagged_user_ids": { "type": "array", "items": { "type": "string" }, "description": "[X] User IDs to tag in photos (max 10)." }, "reply_to_id": { "type": "string", "description": "[X] ID of the tweet to reply to." }, "exclude_reply_user_ids": { "type": "array", "items": { "type": "string" }, "description": "[X] User IDs to exclude from replying." }, "post_mode": { "$ref": "#/components/schemas/TikTokPostMode" }, "privacy_level": { "$ref": "#/components/schemas/TikTokPrivacyLevel" }, "auto_add_music": { "type": "boolean", "description": "[TikTok] Automatically add background music to photos.", "default": false }, "disable_comment": { "type": "boolean", "description": "[TikTok] Disable comments.", "default": false }, "brand_content_toggle": { "type": "boolean", "description": "[TikTok] Paid partnership promoting third-party brands.", "default": false }, "brand_organic_toggle": { "type": "boolean", "description": "[TikTok] Promoting the creator's own business.", "default": false }, "photo_cover_index": { "type": "integer", "description": "[TikTok] Index (0-based) of the photo to use as cover/thumbnail.", "default": 0 }, "tiktok_description": { "type": "string", "description": "[TikTok] Description for photo posts." }, "media_type": { "$ref": "#/components/schemas/InstagramPhotoMediaType" }, "collaborators": { "type": "string", "description": "[Instagram] Comma-separated collaborator usernames." }, "user_tags": { "type": "string", "description": "[Instagram] Comma-separated user tags." }, "location_id": { "type": "string", "description": "[Instagram] Instagram location ID." }, "pinterest_description": { "type": "string", "description": "[Pinterest] Pin description." }, "pinterest_board_id": { "type": "string", "description": "[Pinterest] Board ID. Required when platform includes pinterest." }, "pinterest_alt_text": { "type": "string", "description": "[Pinterest] Alt text for the image." }, "pinterest_link": { "type": "string", "description": "[Pinterest] Destination link for the Pin." }, "subreddit": { "type": "string", "description": "[Reddit] Subreddit name (without 'r/'). Required when platform includes reddit." }, "flair_id": { "type": "string", "description": "[Reddit] Flair ID to apply." } } } } } }, "responses": { "200": { "description": "Upload completed synchronously or async processing started.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SyncUploadResponse" }, { "$ref": "#/components/schemas/AsyncUploadResponse" } ] } } } }, "202": { "description": "Post scheduled or queued successfully.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ScheduledUploadResponse" }, { "$ref": "#/components/schemas/QueuedUploadResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/upload_text": { "post": { "operationId": "uploadText", "summary": "Upload text post", "description": "Upload text-only posts to social media platforms. Supports X (Twitter), LinkedIn, Facebook, Threads, Reddit, Bluesky, Discord, and Telegram. Automatically creates threads on X (>280 chars), Threads (>500 chars), and Bluesky (>300 chars).", "tags": ["Content Upload"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["user", "platform[]", "title"], "properties": { "user": { "type": "string", "description": "User profile identifier." }, "platform[]": { "type": "array", "items": { "$ref": "#/components/schemas/TextPlatformEnum" }, "description": "Platform(s) to upload to." }, "title": { "type": "string", "description": "Default text content for the post." }, "description": { "type": "string", "description": "Optional extended body used on Reddit (becomes post text). Ignored elsewhere." }, "scheduled_date": { "type": "string", "format": "date-time", "description": "ISO-8601 date/time to schedule publishing. Cannot be used with `add_to_queue`." }, "timezone": { "type": "string", "description": "IANA timezone identifier. Defaults to UTC." }, "async_upload": { "type": "boolean", "description": "If true, returns immediately with a `request_id`.", "default": false }, "add_to_queue": { "type": "boolean", "description": "If true, schedules to next queue slot.", "default": false }, "first_comment": { "type": "string", "description": "Automatically post a first comment after publishing." }, "facebook_first_comment": { "type": "string", "description": "[Facebook] Platform-specific first comment." }, "x_first_comment": { "type": "string", "description": "[X] Platform-specific first comment." }, "threads_first_comment": { "type": "string", "description": "[Threads] Platform-specific first comment." }, "reddit_first_comment": { "type": "string", "description": "[Reddit] Platform-specific first comment." }, "bluesky_first_comment": { "type": "string", "description": "[Bluesky] Platform-specific first comment." }, "first_comment_media[]": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "One or more image files to attach to the first comment. Currently supported on Reddit. Not available for scheduled or queued posts." }, "linkedin_title": { "type": "string", "description": "[LinkedIn] Specific text for LinkedIn." }, "x_title": { "type": "string", "description": "[X] Specific text for X." }, "facebook_title": { "type": "string", "description": "[Facebook] Specific text for Facebook." }, "threads_title": { "type": "string", "description": "[Threads] Specific text for Threads." }, "threads_topic_tag": { "type": "string", "description": "[Threads] A topic tag for the post (1-50 characters). Cannot contain periods (.) or ampersands (&). One tag per post.", "maxLength": 50 }, "bluesky_title": { "type": "string", "description": "[Bluesky] Specific text for Bluesky." }, "target_linkedin_page_id": { "type": "string", "description": "[LinkedIn] LinkedIn page ID to post to an organization page." }, "x_long_text_as_post": { "type": "boolean", "description": "[X] When true, long text is published as a single post.", "default": false }, "reply_settings": { "$ref": "#/components/schemas/XReplySettings" }, "quote_tweet_id": { "type": "string", "description": "[X] ID of the tweet to quote. Mutually exclusive with `card_uri`, `poll_options`, and `direct_message_deep_link`." }, "geo_place_id": { "type": "string", "description": "[X] Place ID for geographic location." }, "nullcast": { "type": "boolean", "description": "[X] Publish without broadcasting.", "default": false }, "for_super_followers_only": { "type": "boolean", "description": "[X] Exclusive for super followers.", "default": false }, "community_id": { "type": "string", "description": "[X] Community ID." }, "share_with_followers": { "type": "boolean", "description": "[X] Share community post with followers.", "default": false }, "direct_message_deep_link": { "type": "string", "description": "[X] Direct Message deep link. Mutually exclusive with `card_uri`, `quote_tweet_id`, and `poll_options`." }, "card_uri": { "type": "string", "description": "[X] Card URI for Twitter Cards/ads. Mutually exclusive with `quote_tweet_id`, `direct_message_deep_link`, and `poll_options`." }, "poll_options": { "type": "array", "items": { "type": "string" }, "description": "[X] Array of poll options (2-4 options, max 25 chars each). Mutually exclusive with `card_uri`, `quote_tweet_id`, and `direct_message_deep_link`." }, "poll_duration": { "type": "integer", "description": "[X] Poll duration in minutes (5-10080). Requires `poll_options`.", "default": 1440, "minimum": 5, "maximum": 10080 }, "poll_reply_settings": { "type": "string", "description": "[X] Who can reply to poll. Requires `poll_options`.", "enum": ["following", "mentionedUsers", "subscribers", "verified"] }, "reply_to_id": { "type": "string", "description": "[X/Bluesky] ID or URL of the post to reply to." }, "exclude_reply_user_ids": { "type": "array", "items": { "type": "string" }, "description": "[X] User IDs to exclude from replying. Requires `reply_to_id`." }, "facebook_page_id": { "type": "string", "description": "[Facebook] Facebook Page ID. Required when platform includes facebook. Auto-detected if only one page is connected." }, "facebook_link_url": { "type": "string", "format": "uri", "description": "[Facebook] Optional URL for link preview in text posts. Overrides generic `link_url` for Facebook." }, "link_url": { "type": "string", "format": "uri", "description": "Generic URL to include as a link preview card. Works for LinkedIn, Bluesky, Facebook, and Reddit. Platform-specific parameters (`linkedin_link_url`, `bluesky_link_url`, `facebook_link_url`, `reddit_link_url`) take priority." }, "linkedin_link_url": { "type": "string", "format": "uri", "description": "[LinkedIn] Optional URL for link preview card in text posts. Overrides generic `link_url` for LinkedIn." }, "bluesky_link_url": { "type": "string", "format": "uri", "description": "[Bluesky] Optional URL for external embed link preview in text posts. Overrides generic `link_url` for Bluesky." }, "reddit_link_url": { "type": "string", "format": "uri", "description": "[Reddit] URL for creating a Reddit link post with a URL preview card. Overrides generic `link_url` for Reddit." }, "threads_long_text_as_post": { "type": "boolean", "description": "[Threads] If true, long text is a single post. If false, creates a thread if >500 chars.", "default": false }, "subreddit": { "type": "string", "description": "[Reddit] Subreddit name (without 'r/'). Required when platform includes reddit." }, "flair_id": { "type": "string", "description": "[Reddit] Flair template ID." } } } } } }, "responses": { "200": { "description": "Upload completed synchronously or async processing started.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SyncUploadResponse" }, { "$ref": "#/components/schemas/AsyncUploadResponse" } ] } } } }, "202": { "description": "Post scheduled or queued successfully.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ScheduledUploadResponse" }, { "$ref": "#/components/schemas/QueuedUploadResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/upload_document": { "post": { "operationId": "uploadDocument", "summary": "Upload document", "description": "Upload documents (PDF, PPT, PPTX, DOC, DOCX) to LinkedIn as native document posts displayed as carousels/viewers. Only LinkedIn is supported.", "tags": ["Content Upload"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["user", "platform[]", "document", "title"], "properties": { "user": { "type": "string", "description": "User profile identifier." }, "platform[]": { "type": "array", "items": { "type": "string", "enum": ["linkedin"] }, "description": "Must be [\"linkedin\"]. Only LinkedIn supports document uploads." }, "document": { "type": "string", "format": "binary", "description": "The document file (PDF, PPT, PPTX, DOC, DOCX) or a public URL. Max 100MB, 300 pages." }, "title": { "type": "string", "description": "Document title displayed on the post." }, "description": { "type": "string", "description": "Post commentary/text that appears above the document." }, "visibility": { "$ref": "#/components/schemas/LinkedInVisibility" }, "target_linkedin_page_id": { "type": "string", "description": "LinkedIn page ID to post to a company page instead of personal profile." } } } } } }, "responses": { "200": { "description": "Document uploaded successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/uploadposts/status": { "get": { "operationId": "getUploadStatus", "summary": "Get upload status", "description": "Check the status of asynchronous uploads (via `request_id`) or scheduled posts (via `job_id`). At least one parameter must be provided.", "tags": ["Upload Management"], "parameters": [ { "name": "request_id", "in": "query", "description": "The request identifier returned by upload endpoints when `async_upload=true`.", "schema": { "type": "string" } }, { "name": "job_id", "in": "query", "description": "The job identifier returned by scheduled posts (with `scheduled_date`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadStatusResponse" } } } }, "400": { "description": "Missing both request_id and job_id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "request_id or job_id is required" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/uploadposts/history": { "get": { "operationId": "getUploadHistory", "summary": "Get upload history", "description": "Retrieve a paginated list of past uploads across all platforms, ordered most recent first.", "tags": ["Upload Management"], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Upload history retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/uploadposts/schedule": { "get": { "operationId": "listScheduledPosts", "summary": "List scheduled posts", "description": "Retrieve all pending scheduled posts for the authenticated user.", "tags": ["Upload Management"], "responses": { "200": { "description": "Scheduled posts retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_posts": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledPost" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/uploadposts/schedule/{job_id}": { "delete": { "operationId": "cancelScheduledPost", "summary": "Cancel a scheduled post", "description": "Cancel and delete a scheduled post and its associated assets.", "tags": ["Upload Management"], "parameters": [ { "$ref": "#/components/parameters/JobIdPathParam" } ], "responses": { "200": { "description": "Scheduled post cancelled successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Job abc123 cancelled and assets deleted." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "editScheduledPost", "summary": "Edit a scheduled post", "description": "Update the scheduled date, title, or caption of a scheduled post.", "tags": ["Upload Management"], "parameters": [ { "$ref": "#/components/parameters/JobIdPathParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_date": { "type": "string", "format": "date-time", "description": "New ISO-8601 date/time in UTC. Must be in the future and within 1 year." }, "title": { "type": "string", "description": "New post title/caption." }, "caption": { "type": "string", "description": "New caption/description." } } } } } }, "responses": { "200": { "description": "Scheduled post updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "job_id": { "type": "string" }, "scheduled_date": { "type": "string", "format": "date-time" }, "title": { "type": "string" }, "caption": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/uploadposts/queue/settings": { "get": { "operationId": "getQueueSettings", "summary": "Get queue settings", "description": "Retrieve the current queue configuration (timezone, time slots, active days) for a profile.", "tags": ["Queue System"], "parameters": [ { "$ref": "#/components/parameters/ProfileQueryParam" } ], "responses": { "200": { "description": "Queue settings retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueSettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "updateQueueSettings", "summary": "Update queue settings", "description": "Update the queue configuration (timezone, time slots, active days) for a profile.", "tags": ["Queue System"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["profile_username"], "properties": { "profile_username": { "type": "string", "description": "The profile to update settings for." }, "timezone": { "type": "string", "description": "IANA timezone (e.g., 'Europe/London')." }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/QueueSlot" }, "description": "Array of slot objects. Max 24 slots.", "maxItems": 24 }, "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "description": "Active days: 0=Monday, 1=Tuesday, ..., 6=Sunday." } } } } } }, "responses": { "200": { "description": "Queue settings updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueSettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/uploadposts/queue/preview": { "get": { "operationId": "getQueuePreview", "summary": "Preview queue slots", "description": "Preview the next upcoming queue slots and their availability for a profile.", "tags": ["Queue System"], "parameters": [ { "$ref": "#/components/parameters/ProfileQueryParam" }, { "name": "count", "in": "query", "description": "Number of slots to return.", "schema": { "type": "integer", "default": 10, "maximum": 50 } } ], "responses": { "200": { "description": "Queue preview retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuePreviewResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/uploadposts/queue/next-slot": { "get": { "operationId": "getNextQueueSlot", "summary": "Get next available queue slot", "description": "Get the next available queue slot for a profile.", "tags": ["Queue System"], "parameters": [ { "$ref": "#/components/parameters/ProfileQueryParam" } ], "responses": { "200": { "description": "Next slot retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NextSlotResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/analytics/{profile_username}": { "get": { "operationId": "getAnalytics", "summary": "Get analytics", "description": "Retrieve analytics data for a user profile across one or more social media platforms. Returns metrics like followers, views, impressions, reach, and time series data. Note: Instagram's API renamed 'impressions' to 'views'; both fields are returned for compatibility.", "tags": ["Platform Integration"], "parameters": [ { "name": "profile_username", "in": "path", "required": true, "description": "The unique username of the profile.", "schema": { "type": "string" } }, { "name": "platforms", "in": "query", "required": true, "description": "Comma-separated list of platforms: instagram, tiktok, linkedin, facebook, x, youtube, threads, pinterest, reddit, bluesky.", "schema": { "type": "string" } }, { "name": "page_id", "in": "query", "description": "Required for Facebook analytics. The Facebook Page ID.", "schema": { "type": "string" } }, { "name": "page_urn", "in": "query", "description": "Optional for LinkedIn. Defaults to personal profile. Use Organization URN/ID for pages.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data retrieved successfully. Response keys are platform names with platform-specific metrics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/uploadposts/facebook/pages": { "get": { "operationId": "getFacebookPages", "summary": "Get Facebook pages", "description": "Retrieve Facebook page IDs associated with user profiles. Use the page_id for posting to Facebook pages.", "tags": ["Platform Integration"], "parameters": [ { "name": "profile", "in": "query", "description": "Profile username. If not specified, returns all pages for your account.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Facebook pages retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/FacebookPage" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/uploadposts/linkedin/pages": { "get": { "operationId": "getLinkedInPages", "summary": "Get LinkedIn pages", "description": "Retrieve LinkedIn company pages associated with the authenticated user's accounts. Use the page ID for posting to LinkedIn organization pages.", "tags": ["Platform Integration"], "parameters": [ { "name": "profile", "in": "query", "description": "Profile username. If omitted, returns pages from all connected LinkedIn accounts.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "LinkedIn pages retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedInPage" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/uploadposts/pinterest/boards": { "get": { "operationId": "getPinterestBoards", "summary": "Get Pinterest boards", "description": "Retrieve all Pinterest boards (public and secret) from a connected Pinterest account. Use the board ID for posting Pins.", "tags": ["Platform Integration"], "parameters": [ { "name": "profile", "in": "query", "description": "Profile username. If omitted, uses the first connected Pinterest account.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pinterest boards retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "boards": { "type": "array", "items": { "$ref": "#/components/schemas/PinterestBoard" } }, "pinterest_account_used": { "type": "string", "description": "Pinterest username of the account used." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/uploadposts/reddit/detailed-posts": { "get": { "operationId": "getRedditDetailedPosts", "summary": "Get Reddit detailed posts", "description": "Retrieve detailed posts from a Reddit account connected to a profile, including complete media information. Supports automatic pagination up to 2000 posts.", "tags": ["Platform Integration"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "profile_username", "in": "query", "required": true, "description": "Username of the profile with a connected Reddit account.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reddit posts retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/RedditPost" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/uploadposts/me": { "get": { "operationId": "getCurrentUser", "summary": "Get current user", "description": "Verify the validity of your API key and retrieve basic account information including email and subscription plan.", "tags": ["Authentication"], "responses": { "200": { "description": "API key is valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token is valid" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "plan": { "type": "string", "example": "Professional" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/uploadposts/users": { "post": { "operationId": "createUserProfile", "summary": "Create user profile", "description": "Create a new user profile linked to a user on your platform.", "tags": ["User Management"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["username"], "properties": { "username": { "type": "string", "description": "A unique identifier for the user on your platform." } } } } } }, "responses": { "201": { "description": "Profile created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "profile": { "$ref": "#/components/schemas/UserProfile" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "A profile with this username already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "listUserProfiles", "summary": "List user profiles", "description": "Retrieve a list of all user profiles created under your API key.", "tags": ["User Management"], "responses": { "200": { "description": "Profiles retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "limit": { "type": "integer", "description": "Maximum profiles allowed by plan." }, "plan": { "type": "string", "description": "Subscription plan." }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/UserProfile" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "operationId": "deleteUserProfile", "summary": "Delete user profile", "description": "Delete an existing user profile and its associated data (including social connections).", "tags": ["User Management"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["username"], "properties": { "username": { "type": "string", "description": "The unique identifier of the profile to delete." } } } } } }, "responses": { "200": { "description": "Profile deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Perfil eliminado correctamente" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/uploadposts/users/{username}": { "get": { "operationId": "getUserProfile", "summary": "Get a specific user profile", "description": "Retrieve information for a single user profile by username.", "tags": ["User Management"], "parameters": [ { "name": "username", "in": "path", "required": true, "description": "The username of the profile to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Profile retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "profile": { "$ref": "#/components/schemas/UserProfile" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/uploadposts/users/generate-jwt": { "post": { "operationId": "generateJwt", "summary": "Generate JWT URL", "description": "Generate a secure, single-use URL containing a JWT. Users visit this URL to link their social media accounts. The JWT is valid for 48 hours.", "tags": ["Authentication"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["username"], "properties": { "username": { "type": "string", "description": "The user profile identifier for which the JWT is generated." }, "redirect_url": { "type": "string", "format": "uri", "description": "URL to redirect to after linking social accounts." }, "logo_image": { "type": "string", "format": "uri", "description": "URL to a logo image for branding the linking page." }, "redirect_button_text": { "type": "string", "description": "Text for the redirect button after linking.", "default": "Logout connection" }, "connect_title": { "type": "string", "description": "Custom title for the connection page.", "default": "Connect Social Media Accounts" }, "connect_description": { "type": "string", "description": "Custom description for the connection page.", "default": "Connect your social media accounts to manage your posts." }, "platforms": { "type": "array", "items": { "type": "string", "enum": ["tiktok", "instagram", "linkedin", "youtube", "facebook", "x", "threads", "discord", "telegram"] }, "description": "Platforms to show for connection. Defaults to all supported platforms." }, "show_calendar": { "type": "boolean", "description": "Whether to show the calendar view on the connection page.", "default": true }, "language": { "type": "string", "enum": ["en", "es", "de", "fr", "pt"], "description": "Forces the connection page language for this profile. When omitted, the page auto-detects the visitor's browser language and falls back to English." } } } } } }, "responses": { "200": { "description": "JWT URL generated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "access_url": { "type": "string", "description": "Secure URL for the user to visit and link accounts." }, "duration": { "type": "string", "description": "JWT validity period.", "example": "48h" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/uploadposts/users/validate-jwt": { "post": { "operationId": "validateJwt", "summary": "Validate JWT", "description": "Validate a JWT token and return the associated profile details. Uses Bearer token authentication.", "tags": ["Authentication"], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Validation result. Returns profile if valid, or isValid=false if invalid.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "profile": { "$ref": "#/components/schemas/UserProfile" } } }, { "type": "object", "properties": { "isValid": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "Token expired or invalid signature" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/uploadposts/ffmpeg/jobs/upload": { "post": { "operationId": "createFfmpegJob", "summary": "Create FFmpeg job", "description": "Submit a media processing job using an FFmpeg command template. Supports single or multiple input files via multipart upload or JSON with URLs. Jobs are asynchronous — poll the status endpoint until finished.", "tags": ["FFmpeg Editor"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file", "full_command", "output_extension"], "properties": { "file": { "type": "string", "format": "binary", "description": "Primary media file to process. Referenced as {input} or {input0}." }, "file1": { "type": "string", "format": "binary", "description": "Second input file. Referenced as {input1}." }, "file2": { "type": "string", "format": "binary", "description": "Third input file. Referenced as {input2}." }, "full_command": { "type": "string", "description": "FFmpeg command template using {input}/{input0}, {input1}, etc. and {output} placeholders. Example: 'ffmpeg -y -i {input} -c:v libx264 -crf 23 {output}'" }, "output_extension": { "type": "string", "description": "Desired output file extension (e.g., 'mp4', 'wav', 'mp3', 'mov', 'webm')." }, "publish": { "type": "boolean", "description": "Whether to publish the result." } } } }, "application/json": { "schema": { "type": "object", "required": ["files", "full_command", "output_extension"], "properties": { "files": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Array of input file URLs. Referenced as {input0}, {input1}, etc." }, "full_command": { "type": "string", "description": "FFmpeg command template using {input0}, {input1}, etc. and {output} placeholders." }, "output_extension": { "type": "string", "description": "Desired output file extension." }, "publish": { "type": "boolean", "description": "Whether to publish the result." } } } } } }, "responses": { "202": { "description": "FFmpeg job created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "job_id": { "type": "string", "description": "Unique job identifier for polling status.", "example": "a97bbb5a-139b-46ca-b893-6e8d303d5934" }, "status": { "type": "string", "example": "PENDING" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/uploadposts/ffmpeg/jobs/{job_id}": { "get": { "operationId": "getFfmpegJobStatus", "summary": "Get FFmpeg job status", "description": "Poll the status of an FFmpeg processing job. Statuses: PENDING, PROCESSING, FINISHED, ERROR.", "tags": ["FFmpeg Editor"], "parameters": [ { "$ref": "#/components/parameters/JobIdPathParam" } ], "responses": { "200": { "description": "Job status retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FFmpegJob" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/uploadposts/ffmpeg/jobs/{job_id}/download": { "get": { "operationId": "downloadFfmpegResult", "summary": "Download FFmpeg result", "description": "Download the processed file when job status is FINISHED. Returns binary media with appropriate Content-Type and Content-Disposition headers.", "tags": ["FFmpeg Editor"], "parameters": [ { "$ref": "#/components/parameters/JobIdPathParam" } ], "responses": { "200": { "description": "Processed file download.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/uploadposts/ffmpeg/consumption": { "get": { "operationId": "getFfmpegConsumption", "summary": "Get FFmpeg consumption", "description": "Check your current FFmpeg usage, remaining quota, and processing history for the current month.", "tags": ["FFmpeg Editor"], "responses": { "200": { "description": "Consumption data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FFmpegConsumptionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/uploadposts/users/notifications": { "post": { "operationId": "configureNotifications", "summary": "Configure webhook notifications", "description": "Configure notification preferences for upload events. Supports webhook (POST to your URL) and Telegram notifications.", "tags": ["Webhooks"], "servers": [ { "url": "https://app.upload-post.com/api", "description": "Application server (notifications endpoint)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "object", "properties": { "webhook": { "type": "boolean", "description": "Enable/disable webhook notifications." }, "telegram": { "type": "boolean", "description": "Enable/disable Telegram notifications." } } }, "webhook_url": { "type": "string", "format": "uri", "description": "URL to receive webhook POST requests." }, "telegram_chat_id": { "type": "string", "description": "Telegram chat ID for notifications." }, "webhook_events": { "type": "array", "items": { "type": "string", "enum": ["upload_completed", "social_account.connected", "social_account.disconnected", "social_account.reauth_required"] }, "description": "List of webhook event types to subscribe to. If omitted, all events are enabled." } } } } } }, "responses": { "200": { "description": "Notification settings updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "notifications": { "type": "object", "properties": { "channels": { "type": "object", "properties": { "webhook": { "type": "boolean" }, "telegram": { "type": "boolean" } } }, "webhook_url": { "type": "string" }, "telegram_chat_id": { "type": "string" }, "webhook_events": { "type": "array", "items": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "callbacks": { "uploadCompleted": { "{$request.body#/webhook_url}": { "post": { "summary": "Upload completed webhook", "description": "Sent to your webhook URL when an upload completes (success or failure).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Webhook received successfully." } } } } }, "socialAccountStatusChanged": { "{$request.body#/webhook_url}": { "post": { "summary": "Social account connection status changed", "description": "Sent when a social account is connected, disconnected, or requires re-authentication.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionStatusPayload" } } } }, "responses": { "200": { "description": "Webhook received successfully." } } } } } } } }, "/uploadposts/media": { "get": { "operationId": "getUserMedia", "summary": "Get media list", "description": "Retrieve a list of recent media (posts, reels, videos, pins, tweets, etc.) from a connected social media account. Supports Instagram, TikTok, YouTube, LinkedIn, Facebook, X (Twitter), Threads, Pinterest, Bluesky, and Reddit.", "tags": ["Platform Integration"], "parameters": [ { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "enum": ["instagram", "tiktok", "youtube", "linkedin", "facebook", "x", "threads", "pinterest", "bluesky", "reddit"] }, "description": "The platform to retrieve media from." }, { "name": "user", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Profile username as configured in Upload-Post." }, { "name": "page_urn", "in": "query", "required": false, "schema": { "type": "string" }, "description": "LinkedIn only. Selects which LinkedIn page to fetch posts from. Accepts a numeric organization ID (e.g., 12345), a full URN (e.g., urn:li:organization:12345), or 'me' to force the connected member's personal profile. If omitted, accounts connected as an organization admin auto-resolve to their first administered organization; otherwise the personal profile is used." } ], "responses": { "200": { "description": "Media list retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Platform-specific unique identifier for the media item." }, "caption": { "type": "string", "nullable": true, "description": "Text content, caption, or title of the post." }, "media_type": { "type": "string", "enum": ["IMAGE", "VIDEO", "CAROUSEL_ALBUM", "TEXT"], "description": "Type of media content." }, "media_url": { "type": "string", "nullable": true, "description": "Direct URL to the media file (image or video). Available on most platforms. Returns null for TikTok, YouTube, and when the platform does not provide a direct media URL. URLs are temporary and may expire." }, "permalink": { "type": "string", "nullable": true, "description": "Direct URL to the post on the platform." }, "timestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 timestamp of when the post was created." }, "thumbnail_url": { "type": "string", "nullable": true, "description": "URL of the thumbnail or preview image." } } } } } } } } }, "400": { "description": "Missing or invalid parameters, or platform account not linked." }, "500": { "description": "Internal server error." } } } }, "/uploadposts/comments": { "get": { "operationId": "getPostComments", "summary": "Get Instagram post comments", "description": "Retrieve comments on an Instagram post. Accepts a numeric media ID or a full Instagram post/reel URL. Supports cursor-based pagination via the `after` query parameter — loop while `pagination.has_next` is true. Comments are returned newest-first (reverse-chronological) per Meta Graph API v3.2+; ordering cannot be changed via query parameter.", "tags": ["Instagram Interactions"], "parameters": [ { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "enum": ["instagram"] }, "description": "Must be 'instagram'." }, { "name": "user", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Profile username as configured in Upload-Post." }, { "name": "post_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Numeric Instagram media ID. Use post_id or post_url (one is required)." }, { "name": "post_url", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Full Instagram post or reel URL. Alternative to post_id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Comments per page. Meta caps this edge at 50. Omit to use Meta's default (~25)." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor returned in `pagination.next_cursor` of the previous response. Pass it back to fetch the next page." } ], "responses": { "200": { "description": "Comments retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Comment ID." }, "text": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Commenter's IGSID." }, "username": { "type": "string" } } } } } }, "pagination": { "type": "object", "description": "Cursor pagination metadata.", "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor to pass as `after` for the next page. Null on the last page." }, "has_next": { "type": "boolean", "description": "True if more pages are available." } } } } } } } }, "400": { "description": "Missing parameters, invalid URL, or `limit` out of range (1-50)." }, "500": { "description": "Internal server error." } } } }, "/uploadposts/comments/reply": { "post": { "operationId": "replyToComment", "summary": "Reply to comment (private reply DM)", "description": "Send a private reply (DM) to the author of a comment on your Instagram post. The comment must be less than 7 days old.", "tags": ["Instagram Interactions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["platform", "user", "comment_id", "message"], "properties": { "platform": { "type": "string", "enum": ["instagram"], "description": "Must be 'instagram'." }, "user": { "type": "string", "description": "Profile username as configured in Upload-Post." }, "comment_id": { "type": "string", "description": "ID of the comment to reply to (from Get Post Comments)." }, "message": { "type": "string", "description": "The private reply message text." } } } } } }, "responses": { "200": { "description": "Private reply sent successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "recipient_id": { "type": "string" }, "message_id": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Missing fields or invalid account." }, "429": { "description": "Daily DM limit exceeded." }, "500": { "description": "Internal server error." } } } }, "/uploadposts/dms/conversations": { "get": { "operationId": "getDmConversations", "summary": "Get Instagram DM conversations", "description": "Retrieve the list of Instagram DM conversations for an account, including participants and recent messages.", "tags": ["Instagram Interactions"], "parameters": [ { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "enum": ["instagram"] }, "description": "Must be 'instagram'." }, { "name": "user", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Profile username as configured in Upload-Post." } ], "responses": { "200": { "description": "Conversations retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation thread ID." }, "participants": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Participant IGSID." }, "username": { "type": "string" } } } } } }, "messages": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_time": { "type": "string", "format": "date-time" }, "from": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": "string" } } }, "message": { "type": "string" } } } } } } } } } } } } } }, "400": { "description": "Missing or invalid parameters." }, "500": { "description": "Internal server error." } } } }, "/uploadposts/dms/send": { "post": { "operationId": "sendDm", "summary": "Send Instagram DM", "description": "Send a direct message to an Instagram user using their IGSID. The recipient must have messaged your account first (24-hour messaging window policy enforced by Meta).", "tags": ["Instagram Interactions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["platform", "user", "recipient_id", "message"], "properties": { "platform": { "type": "string", "enum": ["instagram"], "description": "Must be 'instagram'." }, "user": { "type": "string", "description": "Profile username as configured in Upload-Post." }, "recipient_id": { "type": "string", "description": "Instagram-Scoped User ID (IGSID) of the recipient." }, "message": { "type": "string", "description": "The text message to send." } } } } } }, "responses": { "200": { "description": "DM sent successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "recipient_id": { "type": "string" }, "message_id": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Missing fields or invalid account." }, "429": { "description": "Daily DM limit exceeded." }, "500": { "description": "Internal server error." } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "API Key authentication. Format: `Apikey YOUR_API_KEY`" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT Bearer token authentication. Used for validate-jwt and reddit detailed-posts endpoints." } }, "parameters": { "ProfileQueryParam": { "name": "profile_username", "in": "query", "required": true, "description": "The profile username.", "schema": { "type": "string" } }, "JobIdPathParam": { "name": "job_id", "in": "path", "required": true, "description": "The unique job identifier.", "schema": { "type": "string" } }, "PageParam": { "name": "page", "in": "query", "description": "Page number (starts at 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, "LimitParam": { "name": "limit", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer", "default": 10, "enum": [10, 20, 50, 100] } } }, "responses": { "BadRequest": { "description": "Bad Request — Missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized — Invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "message": "Invalid or expired token" } } } }, "Forbidden": { "description": "Forbidden — Plan restrictions or insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Not Found — Resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "Too Many Requests — Monthly limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This upload would exceed your monthly limit." }, "usage": { "$ref": "#/components/schemas/UsageInfo" } } } } } }, "InternalServerError": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "VideoPlatformEnum": { "type": "string", "enum": ["tiktok", "instagram", "linkedin", "youtube", "facebook", "x", "threads", "pinterest", "bluesky", "reddit", "google_business", "discord", "telegram"], "description": "Supported platforms for video upload." }, "PhotoPlatformEnum": { "type": "string", "enum": ["tiktok", "instagram", "linkedin", "facebook", "x", "threads", "pinterest", "bluesky", "reddit", "google_business", "discord", "telegram"], "description": "Supported platforms for photo upload." }, "TextPlatformEnum": { "type": "string", "enum": ["linkedin", "x", "facebook", "threads", "reddit", "bluesky", "google_business", "discord", "telegram"], "description": "Supported platforms for text upload." }, "TikTokPrivacyLevel": { "type": "string", "enum": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"], "description": "[TikTok] Privacy setting for the post.", "default": "PUBLIC_TO_EVERYONE" }, "TikTokPostMode": { "type": "string", "enum": ["DIRECT_POST", "MEDIA_UPLOAD"], "description": "[TikTok] DIRECT_POST publishes immediately. MEDIA_UPLOAD sends to TikTok inbox/drafts for user to finish editing.", "default": "DIRECT_POST" }, "InstagramVideoMediaType": { "type": "string", "enum": ["REELS", "STORIES"], "description": "[Instagram] Type of video media.", "default": "REELS" }, "InstagramPhotoMediaType": { "type": "string", "enum": ["IMAGE", "STORIES"], "description": "[Instagram] Type of photo media. Automatically handles CAROUSEL/REELS logic if mixed media is detected.", "default": "IMAGE" }, "InstagramShareMode": { "type": "string", "enum": ["CUSTOM", "TRIAL_REELS_SHARE_TO_FOLLOWERS_IF_LIKED", "TRIAL_REELS_DONT_SHARE_TO_FOLLOWERS"], "description": "[Instagram] Reel posting mode. CUSTOM = regular Reel. Trial Reel modes test content with non-followers first.", "default": "CUSTOM" }, "LinkedInVisibility": { "type": "string", "enum": ["PUBLIC", "CONNECTIONS", "LOGGED_IN", "CONTAINER"], "description": "[LinkedIn] Visibility setting for the post. Required when platform includes linkedin.", "default": "PUBLIC" }, "YouTubePrivacyStatus": { "type": "string", "enum": ["public", "unlisted", "private"], "description": "[YouTube] Privacy setting for the video.", "default": "public" }, "FacebookVideoMediaType": { "type": "string", "enum": ["REELS", "STORIES"], "description": "[Facebook] Type of video media.", "default": "REELS" }, "FacebookPhotoMediaType": { "type": "string", "enum": ["POSTS", "STORIES"], "description": "[Facebook] Type of photo media.", "default": "POSTS" }, "XReplySettings": { "type": "string", "enum": ["following", "mentionedUsers", "subscribers", "verified"], "description": "[X] Controls who can reply to the tweet." }, "FFmpegJobStatus": { "type": "string", "enum": ["PENDING", "PROCESSING", "FINISHED", "ERROR"], "description": "Status of an FFmpeg processing job." }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" }, "error": { "type": "string" } } }, "UsageInfo": { "type": "object", "properties": { "count": { "type": "integer", "description": "Current usage count." }, "limit": { "type": "integer", "description": "Monthly limit." }, "last_reset": { "type": "string", "format": "date-time", "description": "Last reset timestamp." } } }, "SyncUploadResponse": { "type": "object", "description": "Synchronous upload response (completed within timeout).", "properties": { "success": { "type": "boolean", "example": true }, "results": { "type": "object", "additionalProperties": { "type": "object", "properties": { "success": { "type": "boolean" }, "url": { "type": "string" }, "publish_id": { "type": "string" }, "container_id": { "type": "string" }, "post_id": { "type": "string" }, "video_was_transcoded": { "type": "boolean" }, "changes": { "type": "array", "items": { "type": "string" }, "description": "List of transformations applied to the media." }, "prevalidation_metadata": { "type": "object", "description": "Media metadata detected before upload." }, "error": { "type": "string" } } }, "description": "Per-platform results keyed by platform name." }, "usage": { "$ref": "#/components/schemas/UsageInfo" } } }, "AsyncUploadResponse": { "type": "object", "description": "Asynchronous upload response (processing in background).", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Upload initiated successfully in background." }, "request_id": { "type": "string", "description": "Use this to poll status via GET /uploadposts/status." }, "total_platforms": { "type": "integer", "description": "Number of platforms being uploaded to." } } }, "ScheduledUploadResponse": { "type": "object", "description": "Scheduled upload response.", "properties": { "success": { "type": "boolean", "example": true }, "job_id": { "type": "string", "description": "Scheduled job identifier." }, "scheduled_date": { "type": "string", "format": "date-time", "description": "Scheduled publish date/time in UTC." } } }, "QueuedUploadResponse": { "type": "object", "description": "Queued upload response.", "properties": { "success": { "type": "boolean", "example": true }, "job_id": { "type": "string", "description": "Scheduled job identifier." }, "scheduled_date": { "type": "string", "format": "date-time", "description": "Assigned queue slot date/time." }, "queue_slot": { "type": "string", "format": "date-time", "description": "Queue slot datetime." }, "message": { "type": "string", "example": "Post added to queue" } } }, "DocumentUploadResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "request_id": { "type": "string" }, "results": { "type": "object", "properties": { "linkedin": { "type": "object", "properties": { "success": { "type": "boolean" }, "document_urn": { "type": "string" }, "post_id": { "type": "string" }, "url": { "type": "string" }, "platform": { "type": "string" }, "content_type": { "type": "string" }, "file_size": { "type": "integer" }, "filename": { "type": "string" } } } } } } }, "UploadStatusResponse": { "type": "object", "properties": { "request_id": { "type": "string" }, "job_id": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "in_progress", "completed"], "description": "Aggregated status." }, "completed": { "type": "integer", "description": "Number of platforms completed." }, "total": { "type": "integer", "description": "Total number of platforms." }, "results": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "success": { "type": "boolean" }, "message": { "type": "string" }, "upload_timestamp": { "type": "string", "format": "date-time" } } } }, "last_update": { "type": "string", "format": "date-time" } } }, "UploadHistoryResponse": { "type": "object", "properties": { "history": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryItem" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "HistoryItem": { "type": "object", "properties": { "user_email": { "type": "string" }, "profile_username": { "type": "string" }, "platform": { "type": "string" }, "media_type": { "type": "string", "enum": ["video", "photo", "text"] }, "upload_timestamp": { "type": "string", "format": "date-time" }, "success": { "type": "boolean" }, "platform_post_id": { "type": "string", "nullable": true }, "post_url": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "media_size_bytes": { "type": "integer", "nullable": true }, "post_title": { "type": "string", "nullable": true }, "post_caption": { "type": "string", "nullable": true }, "is_async": { "type": "boolean", "nullable": true }, "job_id": { "type": "string", "nullable": true, "description": "Present when the upload originated from a scheduled job." }, "video_was_transcoded": { "type": "boolean", "nullable": true }, "changes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "List of transformations applied to the media (e.g., transcoding, aspect ratio changes)." }, "prevalidation_metadata": { "type": "object", "nullable": true, "description": "Media metadata detected before upload (dimensions, codec, duration, etc.)." }, "request_id": { "type": "string", "nullable": true }, "request_id_logs": { "type": "string", "nullable": true, "description": "Internal request ID for log correlation." }, "request_total_platforms": { "type": "integer", "nullable": true }, "dashboard": { "type": "boolean", "nullable": true, "description": "Whether the upload was initiated from the dashboard." } } }, "ScheduledPost": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier of the scheduled job." }, "scheduled_date": { "type": "string", "format": "date-time", "description": "ISO-8601 date/time when the post will go live (UTC)." }, "post_type": { "type": "string", "enum": ["video", "photo", "text"], "description": "Type of content." }, "profile_username": { "type": "string" }, "title": { "type": "string" }, "preview_url": { "type": "string", "nullable": true, "description": "Short-lived signed URL to preview the media. Null for text posts." } } }, "QueueSlot": { "type": "object", "properties": { "hour": { "type": "integer", "minimum": 0, "maximum": 23, "description": "Hour of the slot (0-23)." }, "minute": { "type": "integer", "minimum": 0, "maximum": 59, "description": "Minute of the slot (0-59)." } }, "required": ["hour", "minute"] }, "QueueSettings": { "type": "object", "properties": { "timezone": { "type": "string", "description": "IANA timezone.", "example": "America/New_York" }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/QueueSlot" } }, "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "description": "Active days: 0=Monday through 6=Sunday." } } }, "QueueSettingsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "queue_settings": { "$ref": "#/components/schemas/QueueSettings" } } }, "QueuePreviewResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "timezone": { "type": "string" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "datetime_utc": { "type": "string", "format": "date-time" }, "datetime_local": { "type": "string", "format": "date-time" }, "available": { "type": "boolean" }, "is_queue_slot": { "type": "boolean", "description": "Whether this slot is a configured queue slot." }, "scheduled_post": { "type": "object", "nullable": true, "properties": { "job_id": { "type": "string" }, "title": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } } } } } } }, "next_available": { "type": "string", "format": "date-time" } } }, "NextSlotResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "next_slot": { "type": "object", "nullable": true, "properties": { "datetime_utc": { "type": "string", "format": "date-time" }, "datetime_local": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" } } }, "message": { "type": "string", "description": "Present when no slots are available." } } }, "AnalyticsResponse": { "type": "object", "additionalProperties": { "type": "object", "properties": { "followers": { "type": "number" }, "reach": { "type": "number" }, "views": { "type": "number", "description": "Total content views. For Instagram, this is the official 'views' metric (replaces deprecated 'impressions'). Same value as 'impressions' field." }, "impressions": { "type": "number", "description": "Total impressions/views. For Instagram, YouTube, and TikTok this equals the 'views' field. Kept for backwards compatibility." }, "profileViews": { "type": "number", "description": "Profile views or accounts engaged (Instagram)." }, "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" }, "saves": { "type": "number" }, "video_count": { "type": "integer", "description": "Total number of videos (TikTok)." }, "following": { "type": "integer", "description": "Number of accounts followed (TikTok)." }, "reach_timeseries": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "value": { "type": "number" } } } } } }, "description": "Analytics data keyed by platform name. Metrics vary by platform." }, "FacebookPage": { "type": "object", "properties": { "id": { "type": "string", "description": "Facebook Page ID. Use this value as `facebook_page_id` in upload endpoints." }, "name": { "type": "string", "description": "Display name of the Facebook page." }, "picture": { "type": "string", "nullable": true, "description": "URL of the page's profile picture." }, "account_id": { "type": "string", "description": "Internal identifier for the user's connected Facebook account." } } }, "LinkedInPage": { "type": "object", "properties": { "id": { "type": "string", "description": "LinkedIn organization URN. Use as `target_linkedin_page_id`." }, "name": { "type": "string", "description": "Display name of the LinkedIn page." }, "picture": { "type": "string", "nullable": true, "description": "URL of the page logo." }, "account_id": { "type": "string", "description": "Internal identifier for the connected LinkedIn account." }, "vanityName": { "type": "string", "nullable": true, "description": "Custom vanity URL of the page." } } }, "PinterestBoard": { "type": "object", "properties": { "id": { "type": "string", "description": "Pinterest board ID for posting." }, "name": { "type": "string", "description": "Display name of the board." } } }, "RedditPost": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "subreddit": { "type": "string" }, "body": { "type": "string" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "impressions": { "type": "integer" }, "has_image": { "type": "boolean" }, "has_video": { "type": "boolean" }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["image", "video", "external_video"] }, "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "duration": { "type": "number", "description": "Duration in seconds (video only)." }, "thumbnail": { "type": "string", "description": "Thumbnail URL (external_video only)." }, "provider": { "type": "string", "description": "Provider name (external_video only)." } } } }, "url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "thumbnail": { "type": "string" } } }, "UserProfile": { "type": "object", "properties": { "username": { "type": "string", "description": "Unique profile identifier." }, "created_at": { "type": "string", "description": "Timestamp of profile creation." }, "social_accounts": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "username": { "type": "string", "description": "Platform-specific user identifier." }, "handle": { "type": "string", "description": "Platform handle/username." }, "display_name": { "type": "string", "description": "Display name on the platform." }, "social_images": { "type": "string", "description": "URL of the profile picture." }, "reauth_required": { "type": "boolean", "description": "Whether the account needs to be re-authenticated." } } }, { "type": "string" }, { "type": "object", "nullable": true } ] }, "description": "Connected social media accounts keyed by platform name." } } }, "FFmpegJob": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/FFmpegJobStatus" }, "duration_seconds": { "type": "number", "description": "Duration of the input media in seconds." }, "output_extension": { "type": "string" } } }, "FFmpegConsumptionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "consumption": { "type": "object", "properties": { "used_minutes": { "type": "number" }, "remaining_minutes": { "type": "number" }, "quota_minutes": { "type": "number" }, "usage_percentage": { "type": "number" }, "total_requests": { "type": "integer" }, "current_month": { "type": "string" }, "plan": { "type": "string" } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "duration_seconds": { "type": "number" }, "duration_minutes": { "type": "number" }, "timestamp": { "type": "string", "format": "date-time" }, "month": { "type": "string" }, "type": { "type": "string" } } } }, "quota_info": { "type": "object", "properties": { "plan": { "type": "string" }, "quota_minutes": { "type": "number" }, "reset_day": { "type": "integer" }, "next_reset": { "type": "string", "format": "date" } } } } }, "ConnectionStatusPayload": { "type": "object", "description": "Payload sent to your webhook URL when a social account connection status changes.", "properties": { "event": { "type": "string", "enum": ["social_account.connected", "social_account.disconnected", "social_account.reauth_required"], "description": "The connection status event type." }, "user_email": { "type": "string", "description": "The email address of the account owner." }, "platform": { "type": "string", "description": "The social platform (e.g., instagram, youtube, tiktok, x, linkedin, facebook, threads, pinterest, reddit, bluesky, snapchat, google_business, tiktok_business)." }, "account_name": { "type": "string", "description": "The account identifier on the platform." }, "status": { "type": "string", "enum": ["connected", "disconnected", "reauth_required"], "description": "The new connection status." }, "profile_username": { "type": "string", "nullable": true, "description": "The Upload-Post profile associated with this account." }, "reason": { "type": "string", "nullable": true, "description": "Additional context for the status change (e.g., manual_disconnect, account_blocked, token_refresh_threshold_exceeded)." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp of the event in ISO 8601 format." } } }, "WebhookPayload": { "type": "object", "description": "Payload sent to your webhook URL when an upload completes.", "properties": { "event": { "type": "string", "enum": ["upload_completed"], "description": "Event type." }, "user_email": { "type": "string" }, "profile_username": { "type": "string" }, "platform": { "type": "string" }, "media_type": { "type": "string", "enum": ["video", "photo", "text"] }, "title": { "type": "string" }, "caption": { "type": "string" }, "result": { "type": "object", "properties": { "success": { "type": "boolean" }, "url": { "type": "string", "nullable": true }, "publish_id": { "type": "string", "nullable": true }, "post_id": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true } } }, "created_at": { "type": "string", "format": "date-time" } } } } } }