{ "openapi": "3.1.0", "info": { "title": "HumanPost Publishing API", "version": "2.0.0", "description": "Server-to-server publishing, accounts, queues, and analytics." }, "servers": [ { "url": "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi", "description": "Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" } }, "schemas": {}, "parameters": {} }, "paths": { "/v2/openapi.json": { "get": { "summary": "OpenAPI document", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/v2/uploads": { "post": { "summary": "Create an upload", "security": [ { "bearerAuth": [] } ], "description": "Videos must be MP4 with H.264 video and AAC audio when present, no larger than 120 MB or 3 minutes, up to 1080 × 1920 and 60 fps.", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "For video uploads, the filename must use the .mp4 extension." }, "contentType": { "type": "string", "minLength": 1, "maxLength": 100, "description": "For video uploads, use video/mp4." }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "description": "Video uploads may be at most 125,829,120 bytes (120 MiB); images may be at most 52,428,800 bytes (50 MiB)." } }, "required": [ "kind", "filename", "contentType", "sizeBytes" ], "additionalProperties": false, "description": "For videos: MP4, H.264 video, AAC audio when present, 120 MB maximum, 3 minutes maximum, up to 1080 × 1920, and 60 fps maximum." }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "sourceUrl": { "type": "string", "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "kind", "sourceUrl" ], "additionalProperties": false, "description": "Remote video uploads must resolve to an MP4 with H.264 video and AAC audio, no larger than 120 MB or 3 minutes, up to 1080 × 1920 and 60 fps." } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "uploadId": { "type": "string" }, "uploadUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "uploadId", "uploadUrl", "expiresAt" ] }, { "type": "object", "properties": { "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready" ] } }, "required": [ "uploadId", "status" ] } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "415": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/uploads/{uploadId}/complete": { "post": { "summary": "Complete a signed upload", "security": [ { "bearerAuth": [] } ], "description": "Validates uploaded video container, codecs, size, duration, dimensions, and frame rate before marking it ready.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "uploadId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready" ] } }, "required": [ "uploadId", "status" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "415": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/uploads/{uploadId}": { "get": { "summary": "Get upload status", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "uploadId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string" }, "kind": { "type": "string", "enum": [ "video", "image" ] }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ] }, "url": { "type": "string", "format": "uri" }, "thumbnailUrl": { "type": "string", "format": "uri" }, "error": { "type": "string" } }, "required": [ "uploadId", "kind", "status" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/posts": { "post": { "summary": "Create and queue a post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 200, "description": "Optional unique key for safe retries. Repeating a request with the same key returns the original post (HTTP 200) instead of creating a duplicate." }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 10 }, "accountIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 50 }, "caption": { "type": "string", "maxLength": 2200 }, "hashtags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 30 }, "sound": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": "string", "maxLength": 2000 }, "priority": { "type": "integer", "minimum": 0 }, "scheduledAfter": { "type": "string", "format": "date-time" } }, "required": [ "media", "accountIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "media": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "count": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "kind", "count", "thumbnailUrl" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "sound": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "queuedAt": { "type": "string", "format": "date-time" }, "approvedAt": { "type": "string", "format": "date-time" }, "scheduledSlotStart": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "postUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId", "username", "platform", "status", "queuedAt" ] } } }, "required": [ "postId", "status", "media", "caption", "hashtags", "sound", "notes", "createdAt", "accounts" ] } } } }, "201": { "description": "Post created", "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "media": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "count": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "kind", "count", "thumbnailUrl" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "sound": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "queuedAt": { "type": "string", "format": "date-time" }, "approvedAt": { "type": "string", "format": "date-time" }, "scheduledSlotStart": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "postUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId", "username", "platform", "status", "queuedAt" ] } } }, "required": [ "postId", "status", "media", "caption", "hashtags", "sound", "notes", "createdAt", "accounts" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } }, "get": { "summary": "List posts", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "accountId", "in": "query" }, { "schema": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "since", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "media": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "count": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "kind", "count", "thumbnailUrl" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "sound": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "queuedAt": { "type": "string", "format": "date-time" }, "approvedAt": { "type": "string", "format": "date-time" }, "scheduledSlotStart": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "postUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId", "username", "platform", "status", "queuedAt" ] } } }, "required": [ "postId", "status", "media", "caption", "hashtags", "sound", "notes", "createdAt", "accounts" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ] } } } } } } }, "/v2/posts/{postId}/queue": { "post": { "summary": "Queue an existing draft post", "security": [ { "bearerAuth": [] } ], "description": "Adds one queue item per requested account to an existing post whose media is ready.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "postId", "in": "path" }, { "schema": { "type": "string", "maxLength": 200, "description": "Optional unique key for safe retries. Repeating a request with the same key returns the original post (HTTP 200) instead of adding duplicate queue items." }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 50 }, "caption": { "type": "string", "maxLength": 2200 }, "hashtags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 30 }, "sound": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": "string", "maxLength": 2000 }, "priority": { "type": "integer", "minimum": 0 }, "scheduledAfter": { "type": "string", "format": "date-time" } }, "required": [ "accountIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "media": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "count": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "kind", "count", "thumbnailUrl" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "sound": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "queuedAt": { "type": "string", "format": "date-time" }, "approvedAt": { "type": "string", "format": "date-time" }, "scheduledSlotStart": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "postUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId", "username", "platform", "status", "queuedAt" ] } } }, "required": [ "postId", "status", "media", "caption", "hashtags", "sound", "notes", "createdAt", "accounts" ] } } } }, "201": { "description": "Post queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "media": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "count": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "kind", "count", "thumbnailUrl" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "sound": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "queuedAt": { "type": "string", "format": "date-time" }, "approvedAt": { "type": "string", "format": "date-time" }, "scheduledSlotStart": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "postUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId", "username", "platform", "status", "queuedAt" ] } } }, "required": [ "postId", "status", "media", "caption", "hashtags", "sound", "notes", "createdAt", "accounts" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Conflict (`media_not_ready`, `duplicate_queue_item`, or post already published)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/posts/{postId}": { "get": { "summary": "Get a post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "postId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "media": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "count": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "kind", "count", "thumbnailUrl" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "sound": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "queuedAt": { "type": "string", "format": "date-time" }, "approvedAt": { "type": "string", "format": "date-time" }, "scheduledSlotStart": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "postUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId", "username", "platform", "status", "queuedAt" ] } } }, "required": [ "postId", "status", "media", "caption", "hashtags", "sound", "notes", "createdAt", "accounts" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } }, "patch": { "summary": "Update an editable post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "postId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "caption": { "type": "string", "maxLength": 2200 }, "hashtags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 30 }, "sound": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "media": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "count": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "kind", "count", "thumbnailUrl" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "sound": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "queuedAt": { "type": "string", "format": "date-time" }, "approvedAt": { "type": "string", "format": "date-time" }, "scheduledSlotStart": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "postUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId", "username", "platform", "status", "queuedAt" ] } } }, "required": [ "postId", "status", "media", "caption", "hashtags", "sound", "notes", "createdAt", "accounts" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } }, "delete": { "summary": "Cancel a post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "postId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "media": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "count": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "kind", "count", "thumbnailUrl" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "sound": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "queuedAt": { "type": "string", "format": "date-time" }, "approvedAt": { "type": "string", "format": "date-time" }, "scheduledSlotStart": { "type": "string", "format": "date-time" }, "postedAt": { "type": "string", "format": "date-time" }, "postUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId", "username", "platform", "status", "queuedAt" ] } }, "cancellation": { "type": "object", "properties": { "cancelled": { "type": "array", "items": { "type": "string" } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "reason": { "type": "string", "enum": [ "currently_posting", "already_posted", "already_cancelled" ] } }, "required": [ "accountId", "reason" ] } } }, "required": [ "cancelled", "skipped" ] } }, "required": [ "postId", "status", "media", "caption", "hashtags", "sound", "notes", "createdAt", "accounts", "cancellation" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts": { "get": { "summary": "List publishing accounts", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "required": false, "name": "platform", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "username": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "timezone": { "type": "string" }, "followers": { "type": "number" }, "postsToday": { "type": "integer" }, "dailyCap": { "type": "integer" }, "queueDepth": { "type": "integer" }, "nextWindow": { "type": [ "string", "null" ], "format": "date-time" }, "lastPostAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "accountId", "platform", "username", "displayName", "status", "timezone", "followers", "postsToday", "dailyCap", "queueDepth", "nextWindow", "lastPostAt" ] } } }, "required": [ "data" ] } } } } } }, "post": { "summary": "Create a publishing account", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "username": { "type": "string", "minLength": 1, "maxLength": 100 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 150 }, "warmup": { "type": "object", "properties": { "searchTerms": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 1, "maxItems": 20 }, "instructions": { "type": "string", "maxLength": 2000 } }, "required": [ "searchTerms" ], "additionalProperties": false }, "managedPostingEnabled": { "type": "boolean" }, "credentials": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "email", "password" ], "additionalProperties": false } }, "required": [ "platform", "username", "warmup" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "username": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "timezone": { "type": "string" }, "followers": { "type": "number" }, "postsToday": { "type": "integer" }, "dailyCap": { "type": "integer" }, "queueDepth": { "type": "integer" }, "nextWindow": { "type": [ "string", "null" ], "format": "date-time" }, "lastPostAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "accountId", "platform", "username", "displayName", "status", "timezone", "followers", "postsToday", "dailyCap", "queueDepth", "nextWindow", "lastPostAt" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts/{accountId}": { "get": { "summary": "Get a publishing account", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "accountId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "username": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "timezone": { "type": "string" }, "followers": { "type": "number" }, "postsToday": { "type": "integer" }, "dailyCap": { "type": "integer" }, "queueDepth": { "type": "integer" }, "nextWindow": { "type": [ "string", "null" ], "format": "date-time" }, "lastPostAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "accountId", "platform", "username", "displayName", "status", "timezone", "followers", "postsToday", "dailyCap", "queueDepth", "nextWindow", "lastPostAt" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts/{accountId}/queue": { "get": { "summary": "Get an account queue", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "accountId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "postId": { "type": "string" }, "queueItemId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "caption": { "type": "string" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" }, "queuedAt": { "type": "string", "format": "date-time" }, "scheduledSlotStart": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "postId", "queueItemId", "status", "caption", "thumbnailUrl", "queuedAt", "scheduledSlotStart" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ] } } } } } } }, "/v2/posts/{postId}/analytics": { "get": { "summary": "Get post analytics", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "postId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": [ "object", "null" ], "properties": { "views": { "type": "integer", "minimum": 0, "default": 0 }, "likes": { "type": "integer", "minimum": 0, "default": 0 }, "comments": { "type": "integer", "minimum": 0, "default": 0 }, "shares": { "type": "integer", "minimum": 0, "default": 0 }, "saves": { "type": "integer", "minimum": 0, "default": 0 }, "engagementRate": { "type": "number", "minimum": 0, "default": 0 }, "lastUpdated": { "type": "string", "format": "date-time" }, "postUrl": { "type": "string", "format": "uri" }, "accountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "videoId": { "type": "string" }, "accountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "postUrl": { "type": "string" }, "views": { "type": "integer", "minimum": 0 }, "likes": { "type": "integer", "minimum": 0 }, "comments": { "type": "integer", "minimum": 0 }, "shares": { "type": [ "integer", "null" ], "minimum": 0 }, "saves": { "type": [ "integer", "null" ], "minimum": 0 }, "collectedAt": { "type": "string", "format": "date-time" }, "taskId": { "type": [ "string", "null" ] } }, "required": [ "id", "videoId", "accountId", "platform", "postUrl", "views", "likes", "comments", "shares", "saves", "collectedAt" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "summary", "history", "nextCursor" ] } } } } } } }, "/v2/accounts/{accountId}/analytics": { "get": { "summary": "Get account analytics", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "accountId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "followers": { "type": "number" }, "posts": { "type": "number" }, "engagement": { "type": "number" }, "analytics": { "type": "object", "properties": { "views": { "type": "number" }, "likes": { "type": "number" }, "comments": { "type": "number" } }, "required": [ "views", "likes", "comments" ] }, "scannedPosts": { "type": "integer" } }, "required": [ "accountId", "followers", "posts", "engagement", "analytics", "scannedPosts" ] } } } } } } }, "/v2/usage": { "get": { "summary": "Get plan and API usage", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": [ "string", "null" ] }, "billingType": { "type": [ "string", "null" ] }, "videoQuota": { "type": [ "number", "null" ] }, "videoCount": { "type": [ "number", "null" ] }, "postCredits": { "type": [ "object", "null" ], "properties": { "limit": { "type": "number" }, "used": { "type": "number" } }, "required": [ "limit", "used" ] }, "postsPerDay": { "type": "number" }, "apiRequestsToday": { "type": "number" }, "postsCreatedToday": { "type": "number" } }, "required": [ "plan", "billingType", "videoQuota", "videoCount", "postCredits", "postsPerDay", "apiRequestsToday", "postsCreatedToday" ] } } } } } } } }, "webhooks": {} }