{ "openapi": "3.0.3", "info": { "title": "Reeling Developer API", "version": "1.1.0", "description": "Autonomous multi-platform publishing, AI video generation, community question discovery (Reddit & Quora), and pre-publish spam/shadowban detection API across 15 social channels (YouTube, TikTok, Instagram, Facebook, LinkedIn, Threads, Pinterest, Bluesky, X, Reddit, Medium, Quora, Telegram, Discord, Mastodon).", "contact": { "name": "Reeling Developer Support", "email": "mariano@reeling.app", "url": "https://reeling.app/developers" } }, "servers": [ { "url": "https://api.reeling.app/api/v1", "description": "Production Server" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "paths": { "/publish": { "post": { "summary": "Publish or schedule video to multiple social channels", "description": "Ingests a video via public URL or multipart file upload and publishes or schedules it across YouTube Shorts, Instagram Reels, and TikTok.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishJsonRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PublishMultipartRequest" } } } }, "responses": { "200": { "description": "Publishing initiated or scheduled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishResponse" } } } }, "400": { "description": "Bad request or validation error" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Monthly post limit reached or account suspended" }, "502": { "description": "Upstream provider publishing error" } } } }, "/channels": { "get": { "summary": "List connected channels and capabilities for a project", "description": "Returns all connected YouTube, Instagram, and TikTok channels with their IDs, usernames, and platform limits.", "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Target project ID. Optional if your account has only one project." } ], "responses": { "200": { "description": "List of connected channels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelListResponse" } } } }, "401": { "description": "Unauthorized" } } } }, "/channels/{id}/options": { "get": { "summary": "Get publishing options for a connected channel", "description": "Returns available options for a channel, such as Pinterest boards or TikTok creator settings.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Channel UUID" } ], "responses": { "200": { "description": "Channel publishing options (e.g. Pinterest boards)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "channel_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "options": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Channel not found" } } } }, "/projects": { "get": { "summary": "List user projects", "description": "Returns all projects and their corresponding project_id values for the authenticated user.", "responses": { "200": { "description": "List of user projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } } } }, "/posts/{id}": { "get": { "summary": "Get status and published URLs of a post", "description": "Retrieves current status, published URLs, and platform feedback for a specific post.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The post ID returned by /publish" } ], "responses": { "200": { "description": "Post details and publishing status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostStatusResponse" } } } }, "404": { "description": "Post not found" } } } }, "/api-keys": { "get": { "summary": "List active API keys", "responses": { "200": { "description": "List of API keys and usage timestamps" } } }, "post": { "summary": "Create a new API key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Daily AI Video Pipeline" } } } } } }, "responses": { "201": { "description": "API key generated. The raw key is returned only once." } } } }, "/api-keys/{id}": { "delete": { "summary": "Revoke an API key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Key revoked" } } } }, "/ai/adapt": { "post": { "summary": "Adapt video caption/script for multiple platforms", "description": "Transforms a prompt/script into platform-tailored copy with hooks and hashtags for TikTok, Instagram Reels, YouTube Shorts, Threads, and Bluesky.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAdaptRequest" } } } }, "responses": { "200": { "description": "Adapted social copy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAdaptResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } } } }, "/ai/generate-video": { "post": { "summary": "Generate AI video clip via fal.ai MiniMax", "description": "Generates a short-form video clip using text-to-video or image-to-video AI models and saves it directly to Cloudflare R2 storage.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateVideoRequest" } } } }, "responses": { "200": { "description": "Generated video details and public URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateVideoResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient AI credits" } } } }, "/ai/storyboard/create": { "post": { "summary": "Generate structured AI multi-scene storyboard", "description": "Breaks a topic or script into consecutive 5-second cinematic scenes with camera movement, visual prompts, and audio cues.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStoryboardRequest" } } } }, "responses": { "200": { "description": "Storyboard generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStoryboardResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } } } }, "/ai/storyboard/stitch": { "post": { "summary": "Render and stitch storyboard into a continuous video", "description": "Renders storyboard scenes via MiniMax H3 and stitches them into a seamless MP4 using FFmpeg, saving the final video to Cloudflare R2.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StitchStoryboardRequest" } } } }, "responses": { "200": { "description": "Rendered and stitched video details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StitchStoryboardResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient AI credits" } } } }, "/analytics/overview": { "get": { "summary": "Get aggregated cross-platform social analytics", "description": "Retrieves aggregated views, likes, comments, and per-platform performance breakdowns.", "parameters": [ { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Start date in YYYY-MM-DD format" }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "End date in YYYY-MM-DD format" } ], "responses": { "200": { "description": "Aggregated analytics metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsOverviewResponse" } } } }, "401": { "description": "Unauthorized" } } } }, "/analytics/sync": { "post": { "summary": "Trigger live metrics synchronization", "description": "Triggers live sync of engagement metrics directly from social network APIs.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string", "format": "uuid", "description": "Optional post ID to sync specifically" } } } } } }, "responses": { "200": { "description": "Sync completed" }, "401": { "description": "Unauthorized" } } } }, "/inbox/comments": { "get": { "summary": "Retrieve unified social audience comments", "description": "Fetches comments across connected channels into a unified inbox.", "parameters": [ { "name": "platform", "in": "query", "schema": { "type": "string", "default": "all" }, "description": "Filter comments by platform (e.g. youtube, tiktok, instagram, or all)" } ], "responses": { "200": { "description": "Comments list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxCommentsResponse" } } } }, "401": { "description": "Unauthorized" } } } }, "/inbox/reply": { "post": { "operationId": "replyToComment", "summary": "Reply directly to a social comment", "description": "Publishes a reply to an audience comment on the origin platform.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxReplyRequest" } } } }, "responses": { "200": { "description": "Reply posted successfully" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } } } }, "/community/cadence": { "get": { "operationId": "getCommunityCadence", "summary": "Get Reddit & Quora anti-ban cadence quota status", "description": "Returns remaining daily answer slots (max 3/day) and weekly standalone post slots (max 3/week) per platform to prevent automated shadowbans.", "responses": { "200": { "description": "Current 24h answer and 7d post usage and remaining quota per platform" }, "401": { "description": "Unauthorized" } } } }, "/community/discover": { "post": { "operationId": "discoverCommunityQuestions", "summary": "Discover fresh daily Reddit & Quora questions for target topics", "description": "Finds recent high-signal questions on Reddit and Quora matching your niche keywords, along with current anti-ban cadence quota status.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "topics" ], "properties": { "topics": { "type": "array", "items": { "type": "string" }, "description": "Keywords or topics to search (e.g. [\"AI video tools\", \"social media automation\"])" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "reddit", "quora" ] }, "default": [ "reddit", "quora" ] }, "subreddits": { "type": "array", "items": { "type": "string" }, "description": "Optional subreddit allowlist (without r/)" }, "timeRange": { "type": "string", "enum": [ "day", "week", "month" ], "default": "week" }, "limit": { "type": "integer", "default": 10 } } } } } }, "responses": { "200": { "description": "Discovered Reddit and Quora questions plus quota status" }, "401": { "description": "Unauthorized" } } } }, "/community/draft-answer": { "post": { "operationId": "draftCommunityAnswer", "summary": "Draft value-first community answer with Pre-Publish Spam & Shadowban Score", "description": "Generates a non-promotional 120–220 word answer for a Reddit thread or Quora question and evaluates it against deterministic spam and shadowban rules (0–100 Safety Score).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platform", "questionTitle" ], "properties": { "platform": { "type": "string", "enum": [ "reddit", "quora" ] }, "questionTitle": { "type": "string" }, "questionSnippet": { "type": "string" }, "questionUrl": { "type": "string", "format": "uri" }, "subreddit": { "type": "string" }, "expertiseContext": { "type": "string", "description": "First-hand context or expertise to include" }, "includeSoftMention": { "type": "boolean", "default": false }, "brandName": { "type": "string" } } } } } }, "responses": { "200": { "description": "Drafted answer and spamSafety (0-100 score and rule breakdown)" }, "401": { "description": "Unauthorized" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Secret API key starting with rl_live_" }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer authentication with an API key (rl_live_...) or Supabase access token" } }, "schemas": { "PublishJsonRequest": { "type": "object", "required": [ "project_id" ], "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Project ID where connected channels reside" }, "video_url": { "type": "string", "format": "uri", "description": "Direct HTTP/HTTPS link to an MP4, MOV, or WebM video file (up to 100MB)" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Optional direct HTTP/HTTPS link to a JPEG, PNG, or WebP thumbnail/cover image (up to 10MB)" }, "title": { "type": "string", "maxLength": 100, "description": "Video title (used for YouTube and default caption)" }, "caption": { "type": "string", "maxLength": 5000, "description": "Main caption/description and hashtags" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "youtube", "instagram", "tiktok", "linkedin", "pinterest", "threads", "facebook", "bluesky", "telegram", "discord", "mastodon", "reddit", "x", "medium", "quora" ] }, "default": [ "youtube", "instagram", "tiktok" ] }, "reply_to_url": { "type": "string", "format": "uri", "description": "Optional Reddit thread URL or Quora question URL when posting a direct community answer via Reeling Companion" }, "scheduled_for": { "type": "string", "format": "date-time", "description": "Future ISO 8601 timestamp for scheduling. Omit for immediate publishing." }, "youtube": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "privacy_status": { "type": "string", "enum": [ "public", "unlisted", "private" ], "default": "public" }, "made_for_kids": { "type": "boolean", "default": false } } }, "instagram": { "type": "object", "properties": { "caption": { "type": "string" }, "share_to_feed": { "type": "boolean", "default": true } } }, "tiktok": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "inbox", "direct" ], "default": "inbox", "description": "inbox sends to TikTok app for review; direct publishes immediately" }, "title": { "type": "string" }, "privacy_level": { "type": "string", "enum": [ "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY" ], "default": "PUBLIC_TO_EVERYONE" }, "is_aigc": { "type": "boolean", "default": false, "description": "Required if video was generated using AI tools" }, "allow_comment": { "type": "boolean", "default": true }, "allow_duet": { "type": "boolean", "default": true }, "allow_stitch": { "type": "boolean", "default": true } } }, "linkedin": { "type": "object", "properties": { "commentary": { "type": "string", "maxLength": 3000, "description": "Post commentary text" }, "title": { "type": "string", "maxLength": 200, "description": "Video title" } } }, "pinterest": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 100, "description": "Pin title" }, "description": { "type": "string", "maxLength": 500, "description": "Pin description" }, "link": { "type": "string", "format": "uri", "description": "Destination link for the Pin" }, "board_id": { "type": "string", "description": "Specific board ID to pin to" } } }, "threads": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 500, "description": "Threads post text" } } }, "facebook": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 5000, "description": "Facebook post description/caption" }, "title": { "type": "string", "maxLength": 200, "description": "Facebook video title" } } }, "bluesky": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 300, "description": "Bluesky post text" } } }, "telegram": { "type": "object", "properties": { "caption": { "type": "string", "maxLength": 1024, "description": "Telegram video caption" } } }, "discord": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 2000, "description": "Discord message content" } } }, "mastodon": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 500, "description": "Mastodon status text" } } }, "reddit": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 300, "description": "Reddit post title" }, "subreddit": { "type": "string", "description": "Target subreddit name" }, "nsfw": { "type": "boolean", "default": false }, "spoiler": { "type": "boolean", "default": false } } }, "x": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 280, "description": "X (Twitter) post text" }, "reply_settings": { "type": "string", "enum": [ "everyone", "following", "mentionedUsers" ], "default": "everyone" } } }, "medium": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 150, "description": "Medium story title" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Up to 5 Medium tags" }, "publish_status": { "type": "string", "enum": [ "public", "draft", "unlisted" ], "default": "public" } } }, "quora": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 250, "description": "Quora post title or target question heading" }, "target_url": { "type": "string", "format": "uri", "description": "Optional Quora question or Space URL" } } } } }, "PublishMultipartRequest": { "type": "object", "required": [ "project_id", "video" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "video": { "type": "string", "format": "binary", "description": "MP4, MOV, or WebM video file (up to 100MB)" }, "thumbnail": { "type": "string", "format": "binary", "description": "Optional JPEG, PNG, or WebP thumbnail image file (up to 10MB)" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Optional direct HTTP/HTTPS link to thumbnail image (up to 10MB)" }, "title": { "type": "string" }, "caption": { "type": "string" }, "platforms": { "type": "string", "description": "JSON array string, e.g. [\"youtube\",\"instagram\",\"tiktok\"]" }, "scheduled_for": { "type": "string", "format": "date-time" } } }, "PublishResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "post_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "published", "partially_published", "scheduled", "failed" ] }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "channel_title": { "type": "string" }, "success": { "type": "boolean" }, "published": { "type": "boolean" }, "id": { "type": "string" }, "url": { "type": "string" }, "error": { "type": "string" } } } } } }, "ChannelListResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "project_id": { "type": "string", "format": "uuid" }, "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "name": { "type": "string" }, "username": { "type": "string" }, "avatar_url": { "type": "string" }, "external_account_id": { "type": "string" }, "capabilities": { "type": "object" } } } } } }, "PostStatusResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "published_at": { "type": "string", "format": "date-time" }, "publish_results": { "type": "array", "items": { "type": "object" } } } }, "AiAdaptRequest": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Core script or concept" }, "platforms": { "type": "array", "items": { "type": "string" }, "default": [ "tiktok", "instagram", "youtube", "threads", "bluesky" ] }, "tone": { "type": "string", "enum": [ "viral", "engaging", "educational", "humorous", "professional" ], "default": "viral" }, "includeJev": { "type": "boolean", "default": false } } }, "AiAdaptResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "adapted": { "type": "object" }, "model": { "type": "string" } } }, "GenerateVideoRequest": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Text prompt describing the video scene" }, "imageUrl": { "type": "string", "format": "uri", "description": "Optional initial image URL for image-to-video" }, "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9" ], "default": "9:16" }, "apiKey": { "type": "string", "description": "Optional custom fal.ai key" } } }, "GenerateVideoResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "videoUrl": { "type": "string", "format": "uri" }, "requestId": { "type": "string" }, "aspectRatio": { "type": "string" } } }, "CreateStoryboardRequest": { "type": "object", "required": [ "topic" ], "properties": { "topic": { "type": "string", "description": "Narrative script or concept" }, "durationSeconds": { "type": "integer", "default": 30 }, "style": { "type": "string" }, "camera": { "type": "string" } } }, "CreateStoryboardResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "storyboard": { "type": "object", "properties": { "scenes": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "prompt": { "type": "string" }, "timecode": { "type": "string" }, "audioCue": { "type": "string" } } } } } } } }, "StitchStoryboardRequest": { "type": "object", "required": [ "scenes" ], "properties": { "scenes": { "type": "array", "items": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string" }, "videoUrl": { "type": "string", "format": "uri" }, "title": { "type": "string" } } } }, "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9" ], "default": "9:16" }, "apiKey": { "type": "string" } } }, "StitchStoryboardResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "videoUrl": { "type": "string", "format": "uri" }, "duration": { "type": "number" } } }, "AnalyticsOverviewResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "totalViews": { "type": "number" }, "totalLikes": { "type": "number" }, "totalComments": { "type": "number" }, "totalImpressions": { "type": "number" }, "platformBreakdown": { "type": "object" } } }, "InboxCommentsResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "author": { "type": "string" }, "text": { "type": "string" }, "created_at": { "type": "string" } } } } } }, "InboxReplyRequest": { "type": "object", "required": [ "commentId", "platform", "replyText" ], "properties": { "commentId": { "type": "string" }, "platform": { "type": "string" }, "replyText": { "type": "string" } } } } } }