{ "openapi": "3.1.0", "info": { "title": "HumanPost API", "version": "2.4.0", "description": "Server-to-server company tasks, publishing, content tagging, accounts, queues, analytics, and workspace reads." }, "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/task-types": { "get": { "summary": "Discover task capabilities", "security": [ { "bearerAuth": [] } ], "description": "Requires tasks:read. Optionally pass accountId to inspect eligibility. Old blank-task-capable apps support new Amplify bundles. Worker business hours and HumanPost review apply.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\x00-\\x1f\\x7f]+$" }, "required": false, "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "comment_video", "amplify_video" ] }, "platforms": { "type": "array", "items": { "type": "string" } }, "requiredPayloadFields": { "type": "array", "items": { "type": "string" } }, "creditKind": { "type": "string" }, "creditQuantity": { "type": "number" }, "evidence": { "type": "string" }, "available": { "type": "boolean" }, "blockers": { "type": "array", "items": { "type": "string" } }, "actions": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "platforms", "requiredPayloadFields", "creditKind", "creditQuantity", "evidence", "available", "blockers", "actions" ] } }, "scheduling": { "type": "string", "enum": [ "worker_business_hours" ] }, "review": { "type": "string", "enum": [ "humanpost" ] }, "accountId": { "type": [ "string", "null" ] } }, "required": [ "data", "scheduling", "review", "accountId" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/tasks": { "post": { "summary": "Create a comment or Amplify task", "security": [ { "bearerAuth": [] } ], "description": "Requires tasks:write and Idempotency-Key. Reserves one Comment or Amplify credit atomically. Amplify is one public task with separately reviewed Repost + Like and Comment components. Keys are company-scoped; changed payloads conflict. Worker business hours apply. No admin, worker, payout or approval overrides.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\x00-\\x1f\\x7f]+$" }, "externalReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "comment_video" ] }, "payload": { "type": "object", "properties": { "targetVideoUrl": { "type": "string", "maxLength": 2000, "format": "uri" }, "commentText": { "type": "string", "minLength": 1, "maxLength": 500 }, "commentImageUrl": { "type": "string", "maxLength": 2000, "format": "uri" }, "allowAccountRollover": { "type": "boolean", "default": false } }, "required": [ "targetVideoUrl", "commentText" ], "additionalProperties": false } }, "required": [ "accountId", "type", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\x00-\\x1f\\x7f]+$" }, "externalReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "amplify_video" ] }, "payload": { "type": "object", "properties": { "targetVideoUrl": { "type": "string", "maxLength": 2000, "format": "uri" }, "commentText": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "targetVideoUrl", "commentText" ], "additionalProperties": false } }, "required": [ "accountId", "type", "payload" ], "additionalProperties": false } ] }, "example": { "accountId": "ACCOUNT_ID", "type": "amplify_video", "externalReference": "partner-order-123", "payload": { "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456", "commentText": "hi" } } } } }, "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "companyId": { "type": "string" }, "type": { "type": "string", "enum": [ "post_video", "amplify_video", "repost_like_video", "like_video", "comment_video", "reply_to_comment", "like_comment", "follow_account", "edit_bio", "edit_username", "edit_display_name", "update_profile_pic", "account_login", "account_logout", "account_setup", "warmup_scroll", "record_fyp", "record_reels", "intro_video", "spark_code", "connect_posting_service", "delete_post", "delete_account", "blank_task" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "accountId": { "type": [ "string", "null" ] }, "currentAccountId": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "externalReference": { "type": [ "string", "null" ] }, "payload": { "type": "object", "properties": { "targetVideoUrl": { "type": "string" }, "commentText": { "type": "string" }, "commentImageAvailable": { "type": "boolean" }, "allowAccountRollover": { "type": "boolean" }, "replyText": { "type": "string" }, "directCommentUrl": { "type": "string" }, "commentAuthor": { "type": "string" }, "tiktokUrl": { "type": "string" }, "title": { "type": "string" }, "bio": { "type": "string" }, "username": { "type": "string" }, "displayName": { "type": "string" }, "newBio": { "type": "string" }, "newUsername": { "type": "string" }, "newDisplayName": { "type": "string" }, "videoId": { "type": "string" }, "profilePictureAvailable": { "type": "boolean" } } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "currentAttemptId": { "type": "string" }, "availableActions": { "type": "array", "items": { "type": "string", "enum": [ "cancel", "resume" ] } }, "evidenceAvailable": { "type": "boolean" }, "credit": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "source": { "type": [ "string", "null" ] }, "outcome": { "type": "string", "enum": [ "reserved", "consumed", "refunded", "not_charged" ] } }, "required": [ "kind", "quantity", "source", "outcome" ] }, "historyComplete": { "type": "boolean" } }, "required": [ "taskId", "companyId", "type", "status", "accountId", "currentAccountId", "platform", "externalReference", "payload", "createdAt", "updatedAt", "completedAt", "reason", "components", "attempts", "currentAttemptId", "availableActions", "evidenceAvailable", "credit", "historyComplete" ] }, "example": { "taskId": "AMPLIFY_TASK_ID", "companyId": "COMPANY_ID", "type": "amplify_video", "status": "assigned", "accountId": "ACCOUNT_ID", "currentAccountId": "ACCOUNT_ID", "platform": "tiktok", "externalReference": "partner-order-123", "payload": { "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456", "commentText": "hi" }, "createdAt": "2027-01-01T00:00:00Z", "updatedAt": "2027-01-01T00:00:00Z", "completedAt": null, "reason": null, "components": [ { "taskId": "REPOST_LIKE_TASK_ID", "role": "repost_like", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false }, { "taskId": "COMMENT_TASK_ID", "role": "comment", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "attempts": [ { "taskId": "AMPLIFY_TASK_ID", "role": "attempt_1", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "currentAttemptId": "AMPLIFY_TASK_ID", "availableActions": [ "cancel" ], "evidenceAvailable": false, "credit": { "kind": "amplify", "quantity": 1, "source": "monthly", "outcome": "reserved" }, "historyComplete": true } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "companyId": { "type": "string" }, "type": { "type": "string", "enum": [ "post_video", "amplify_video", "repost_like_video", "like_video", "comment_video", "reply_to_comment", "like_comment", "follow_account", "edit_bio", "edit_username", "edit_display_name", "update_profile_pic", "account_login", "account_logout", "account_setup", "warmup_scroll", "record_fyp", "record_reels", "intro_video", "spark_code", "connect_posting_service", "delete_post", "delete_account", "blank_task" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "accountId": { "type": [ "string", "null" ] }, "currentAccountId": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "externalReference": { "type": [ "string", "null" ] }, "payload": { "type": "object", "properties": { "targetVideoUrl": { "type": "string" }, "commentText": { "type": "string" }, "commentImageAvailable": { "type": "boolean" }, "allowAccountRollover": { "type": "boolean" }, "replyText": { "type": "string" }, "directCommentUrl": { "type": "string" }, "commentAuthor": { "type": "string" }, "tiktokUrl": { "type": "string" }, "title": { "type": "string" }, "bio": { "type": "string" }, "username": { "type": "string" }, "displayName": { "type": "string" }, "newBio": { "type": "string" }, "newUsername": { "type": "string" }, "newDisplayName": { "type": "string" }, "videoId": { "type": "string" }, "profilePictureAvailable": { "type": "boolean" } } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "currentAttemptId": { "type": "string" }, "availableActions": { "type": "array", "items": { "type": "string", "enum": [ "cancel", "resume" ] } }, "evidenceAvailable": { "type": "boolean" }, "credit": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "source": { "type": [ "string", "null" ] }, "outcome": { "type": "string", "enum": [ "reserved", "consumed", "refunded", "not_charged" ] } }, "required": [ "kind", "quantity", "source", "outcome" ] }, "historyComplete": { "type": "boolean" } }, "required": [ "taskId", "companyId", "type", "status", "accountId", "currentAccountId", "platform", "externalReference", "payload", "createdAt", "updatedAt", "completedAt", "reason", "components", "attempts", "currentAttemptId", "availableActions", "evidenceAvailable", "credit", "historyComplete" ] }, "example": { "taskId": "AMPLIFY_TASK_ID", "companyId": "COMPANY_ID", "type": "amplify_video", "status": "assigned", "accountId": "ACCOUNT_ID", "currentAccountId": "ACCOUNT_ID", "platform": "tiktok", "externalReference": "partner-order-123", "payload": { "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456", "commentText": "hi" }, "createdAt": "2027-01-01T00:00:00Z", "updatedAt": "2027-01-01T00:00:00Z", "completedAt": null, "reason": null, "components": [ { "taskId": "REPOST_LIKE_TASK_ID", "role": "repost_like", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false }, { "taskId": "COMMENT_TASK_ID", "role": "comment", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "attempts": [ { "taskId": "AMPLIFY_TASK_ID", "role": "attempt_1", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "currentAttemptId": "AMPLIFY_TASK_ID", "availableActions": [ "cancel" ], "evidenceAvailable": false, "credit": { "kind": "amplify", "quantity": 1, "source": "monthly", "outcome": "reserved" }, "historyComplete": true } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } }, "get": { "summary": "List company tasks", "security": [ { "bearerAuth": [] } ], "description": "Requires tasks:read. Bounds each scanned page; follow nextCursor even after an empty filtered page. Hides operational children/replacements and reports their effective outcome under the original task ID. Legacy tasks missing companyId are accessible by ID after account ownership verification, but absent from this company-indexed list.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 2000 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "post_video", "amplify_video", "repost_like_video", "like_video", "comment_video", "reply_to_comment", "like_comment", "follow_account", "edit_bio", "edit_username", "edit_display_name", "update_profile_pic", "account_login", "account_logout", "account_setup", "warmup_scroll", "record_fyp", "record_reels", "intro_video", "spark_code", "connect_posting_service", "delete_post", "delete_account", "blank_task" ] }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\x00-\\x1f\\x7f]+$" }, "required": false, "name": "accountId", "in": "query" }, { "schema": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "required": false, "name": "platform", "in": "query" }, { "schema": { "type": "string", "maxLength": 200 }, "required": false, "name": "externalReference", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "createdAfter", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "createdBefore", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "companyId": { "type": "string" }, "type": { "type": "string", "enum": [ "post_video", "amplify_video", "repost_like_video", "like_video", "comment_video", "reply_to_comment", "like_comment", "follow_account", "edit_bio", "edit_username", "edit_display_name", "update_profile_pic", "account_login", "account_logout", "account_setup", "warmup_scroll", "record_fyp", "record_reels", "intro_video", "spark_code", "connect_posting_service", "delete_post", "delete_account", "blank_task" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "accountId": { "type": [ "string", "null" ] }, "currentAccountId": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "externalReference": { "type": [ "string", "null" ] }, "payload": { "type": "object", "properties": { "targetVideoUrl": { "type": "string" }, "commentText": { "type": "string" }, "commentImageAvailable": { "type": "boolean" }, "allowAccountRollover": { "type": "boolean" }, "replyText": { "type": "string" }, "directCommentUrl": { "type": "string" }, "commentAuthor": { "type": "string" }, "tiktokUrl": { "type": "string" }, "title": { "type": "string" }, "bio": { "type": "string" }, "username": { "type": "string" }, "displayName": { "type": "string" }, "newBio": { "type": "string" }, "newUsername": { "type": "string" }, "newDisplayName": { "type": "string" }, "videoId": { "type": "string" }, "profilePictureAvailable": { "type": "boolean" } } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "currentAttemptId": { "type": "string" }, "availableActions": { "type": "array", "items": { "type": "string", "enum": [ "cancel", "resume" ] } }, "evidenceAvailable": { "type": "boolean" }, "credit": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "source": { "type": [ "string", "null" ] }, "outcome": { "type": "string", "enum": [ "reserved", "consumed", "refunded", "not_charged" ] } }, "required": [ "kind", "quantity", "source", "outcome" ] }, "historyComplete": { "type": "boolean" } }, "required": [ "taskId", "companyId", "type", "status", "accountId", "currentAccountId", "platform", "externalReference", "payload", "createdAt", "updatedAt", "completedAt", "reason", "components", "attempts", "currentAttemptId", "availableActions", "evidenceAvailable", "credit", "historyComplete" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ] }, "example": { "data": [ { "taskId": "AMPLIFY_TASK_ID", "companyId": "COMPANY_ID", "type": "amplify_video", "status": "assigned", "accountId": "ACCOUNT_ID", "currentAccountId": "ACCOUNT_ID", "platform": "tiktok", "externalReference": "partner-order-123", "payload": { "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456", "commentText": "hi" }, "createdAt": "2027-01-01T00:00:00Z", "updatedAt": "2027-01-01T00:00:00Z", "completedAt": null, "reason": null, "components": [ { "taskId": "REPOST_LIKE_TASK_ID", "role": "repost_like", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false }, { "taskId": "COMMENT_TASK_ID", "role": "comment", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "attempts": [ { "taskId": "AMPLIFY_TASK_ID", "role": "attempt_1", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "currentAttemptId": "AMPLIFY_TASK_ID", "availableActions": [ "cancel" ], "evidenceAvailable": false, "credit": { "kind": "amplify", "quantity": 1, "source": "monthly", "outcome": "reserved" }, "historyComplete": true } ], "nextCursor": null } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/tasks/{taskId}": { "get": { "summary": "Inspect task progress", "security": [ { "bearerAuth": [] } ], "description": "Requires tasks:read. Read combined Amplify components or comment replacement attempts. Completed means approved by HumanPost, not merely submitted. Use availableActions to discover supported controls. Operational child IDs cannot be queried independently through this company interface.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\x00-\\x1f\\x7f]+$" }, "required": true, "name": "taskId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "companyId": { "type": "string" }, "type": { "type": "string", "enum": [ "post_video", "amplify_video", "repost_like_video", "like_video", "comment_video", "reply_to_comment", "like_comment", "follow_account", "edit_bio", "edit_username", "edit_display_name", "update_profile_pic", "account_login", "account_logout", "account_setup", "warmup_scroll", "record_fyp", "record_reels", "intro_video", "spark_code", "connect_posting_service", "delete_post", "delete_account", "blank_task" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "accountId": { "type": [ "string", "null" ] }, "currentAccountId": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "externalReference": { "type": [ "string", "null" ] }, "payload": { "type": "object", "properties": { "targetVideoUrl": { "type": "string" }, "commentText": { "type": "string" }, "commentImageAvailable": { "type": "boolean" }, "allowAccountRollover": { "type": "boolean" }, "replyText": { "type": "string" }, "directCommentUrl": { "type": "string" }, "commentAuthor": { "type": "string" }, "tiktokUrl": { "type": "string" }, "title": { "type": "string" }, "bio": { "type": "string" }, "username": { "type": "string" }, "displayName": { "type": "string" }, "newBio": { "type": "string" }, "newUsername": { "type": "string" }, "newDisplayName": { "type": "string" }, "videoId": { "type": "string" }, "profilePictureAvailable": { "type": "boolean" } } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "currentAttemptId": { "type": "string" }, "availableActions": { "type": "array", "items": { "type": "string", "enum": [ "cancel", "resume" ] } }, "evidenceAvailable": { "type": "boolean" }, "credit": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "source": { "type": [ "string", "null" ] }, "outcome": { "type": "string", "enum": [ "reserved", "consumed", "refunded", "not_charged" ] } }, "required": [ "kind", "quantity", "source", "outcome" ] }, "historyComplete": { "type": "boolean" } }, "required": [ "taskId", "companyId", "type", "status", "accountId", "currentAccountId", "platform", "externalReference", "payload", "createdAt", "updatedAt", "completedAt", "reason", "components", "attempts", "currentAttemptId", "availableActions", "evidenceAvailable", "credit", "historyComplete" ] }, "example": { "taskId": "AMPLIFY_TASK_ID", "companyId": "COMPANY_ID", "type": "amplify_video", "status": "assigned", "accountId": "ACCOUNT_ID", "currentAccountId": "ACCOUNT_ID", "platform": "tiktok", "externalReference": "partner-order-123", "payload": { "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456", "commentText": "hi" }, "createdAt": "2027-01-01T00:00:00Z", "updatedAt": "2027-01-01T00:00:00Z", "completedAt": null, "reason": null, "components": [ { "taskId": "REPOST_LIKE_TASK_ID", "role": "repost_like", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false }, { "taskId": "COMMENT_TASK_ID", "role": "comment", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "attempts": [ { "taskId": "AMPLIFY_TASK_ID", "role": "attempt_1", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "currentAttemptId": "AMPLIFY_TASK_ID", "availableActions": [ "cancel" ], "evidenceAvailable": false, "credit": { "kind": "amplify", "quantity": 1, "source": "monthly", "outcome": "reserved" }, "historyComplete": true } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/tasks/{taskId}/events": { "get": { "summary": "Read task history", "security": [ { "bearerAuth": [] } ], "description": "Requires tasks:read. Persisted revisions arrive asynchronously and may be delivered out of order; eventId deduplicates, revision identifies the document version. historyComplete is false for legacy work. Poll without a cursor to see newer events; cursors page backward through history.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\x00-\\x1f\\x7f]+$" }, "required": true, "name": "taskId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 2000 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string" }, "taskId": { "type": "string" }, "operationalTaskId": { "type": "string" }, "role": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "revision": { "type": "string" }, "kind": { "type": "string", "enum": [ "created", "updated", "deleted" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "reason": { "type": [ "string", "null" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "creditOutcome": { "type": "string" } }, "required": [ "eventId", "taskId", "operationalTaskId", "role", "occurredAt", "revision", "kind", "status", "reason", "scheduledFor", "submittedAt", "reviewedAt", "creditOutcome" ] } }, "nextCursor": { "type": [ "string", "null" ] }, "historyComplete": { "type": "boolean" } }, "required": [ "data", "nextCursor", "historyComplete" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/tasks/{taskId}/evidence": { "get": { "summary": "Read task screenshots", "security": [ { "bearerAuth": [] } ], "description": "Requires tasks:evidence:read. Pages current evidence then archived Amplify proof. Follow nextCursor even after an empty page. Company-authorized screenshots use signed URLs valid for 60–3600 seconds. URLs are bearer links until expiry. Never exposes permanent Firebase download tokens or worker personal records.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\x00-\\x1f\\x7f]+$" }, "required": true, "name": "taskId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 2000 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 900 }, "required": false, "name": "expiresInSeconds", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "evidenceId": { "type": "string" }, "taskId": { "type": "string" }, "operationalTaskId": { "type": "string" }, "role": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "historical": { "type": "boolean" } }, "required": [ "evidenceId", "taskId", "operationalTaskId", "role", "url", "expiresAt", "submittedAt", "reviewedAt", "status", "historical" ] } }, "nextCursor": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "data", "nextCursor", "expiresAt" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/tasks/{taskId}/cancel": { "post": { "summary": "Cancel remaining task work", "security": [ { "bearerAuth": [] } ], "description": "Requires tasks:write. Supports unfinished Comment and Amplify requests. Retains proof/history; cannot undo platform actions. Amplify refunds only when neither component was approved. Idempotent repeats do not refund twice. Old-period refunds do not replenish a new period.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\x00-\\x1f\\x7f]+$" }, "required": true, "name": "taskId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "companyId": { "type": "string" }, "type": { "type": "string", "enum": [ "post_video", "amplify_video", "repost_like_video", "like_video", "comment_video", "reply_to_comment", "like_comment", "follow_account", "edit_bio", "edit_username", "edit_display_name", "update_profile_pic", "account_login", "account_logout", "account_setup", "warmup_scroll", "record_fyp", "record_reels", "intro_video", "spark_code", "connect_posting_service", "delete_post", "delete_account", "blank_task" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "accountId": { "type": [ "string", "null" ] }, "currentAccountId": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "externalReference": { "type": [ "string", "null" ] }, "payload": { "type": "object", "properties": { "targetVideoUrl": { "type": "string" }, "commentText": { "type": "string" }, "commentImageAvailable": { "type": "boolean" }, "allowAccountRollover": { "type": "boolean" }, "replyText": { "type": "string" }, "directCommentUrl": { "type": "string" }, "commentAuthor": { "type": "string" }, "tiktokUrl": { "type": "string" }, "title": { "type": "string" }, "bio": { "type": "string" }, "username": { "type": "string" }, "displayName": { "type": "string" }, "newBio": { "type": "string" }, "newUsername": { "type": "string" }, "newDisplayName": { "type": "string" }, "videoId": { "type": "string" }, "profilePictureAvailable": { "type": "boolean" } } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "currentAttemptId": { "type": "string" }, "availableActions": { "type": "array", "items": { "type": "string", "enum": [ "cancel", "resume" ] } }, "evidenceAvailable": { "type": "boolean" }, "credit": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "source": { "type": [ "string", "null" ] }, "outcome": { "type": "string", "enum": [ "reserved", "consumed", "refunded", "not_charged" ] } }, "required": [ "kind", "quantity", "source", "outcome" ] }, "historyComplete": { "type": "boolean" } }, "required": [ "taskId", "companyId", "type", "status", "accountId", "currentAccountId", "platform", "externalReference", "payload", "createdAt", "updatedAt", "completedAt", "reason", "components", "attempts", "currentAttemptId", "availableActions", "evidenceAvailable", "credit", "historyComplete" ] }, "example": { "taskId": "AMPLIFY_TASK_ID", "companyId": "COMPANY_ID", "type": "amplify_video", "status": "cancelled", "accountId": "ACCOUNT_ID", "currentAccountId": "ACCOUNT_ID", "platform": "tiktok", "externalReference": "partner-order-123", "payload": { "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456", "commentText": "hi" }, "createdAt": "2027-01-01T00:00:00Z", "updatedAt": "2027-01-01T00:00:00Z", "completedAt": null, "reason": "Customer cancelled", "components": [ { "taskId": "REPOST_LIKE_TASK_ID", "role": "repost_like", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "cancelled", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false }, { "taskId": "COMMENT_TASK_ID", "role": "comment", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "cancelled", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "attempts": [ { "taskId": "AMPLIFY_TASK_ID", "role": "attempt_1", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "cancelled", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "currentAttemptId": "AMPLIFY_TASK_ID", "availableActions": [], "evidenceAvailable": false, "credit": { "kind": "amplify", "quantity": 1, "source": "monthly", "outcome": "refunded" }, "historyComplete": true } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/tasks/{taskId}/resume": { "post": { "summary": "Resume blocked Amplify work", "security": [ { "bearerAuth": [] } ], "description": "Requires tasks:write. Reopens failed/expired Amplify components on the original account/worker; approved work stays completed. Worker business hours and dispatch availability apply. No new credit is charged. Standalone comments follow their existing automatic replacement policy.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\x00-\\x1f\\x7f]+$" }, "required": true, "name": "taskId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "companyId": { "type": "string" }, "type": { "type": "string", "enum": [ "post_video", "amplify_video", "repost_like_video", "like_video", "comment_video", "reply_to_comment", "like_comment", "follow_account", "edit_bio", "edit_username", "edit_display_name", "update_profile_pic", "account_login", "account_logout", "account_setup", "warmup_scroll", "record_fyp", "record_reels", "intro_video", "spark_code", "connect_posting_service", "delete_post", "delete_account", "blank_task" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "accountId": { "type": [ "string", "null" ] }, "currentAccountId": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "externalReference": { "type": [ "string", "null" ] }, "payload": { "type": "object", "properties": { "targetVideoUrl": { "type": "string" }, "commentText": { "type": "string" }, "commentImageAvailable": { "type": "boolean" }, "allowAccountRollover": { "type": "boolean" }, "replyText": { "type": "string" }, "directCommentUrl": { "type": "string" }, "commentAuthor": { "type": "string" }, "tiktokUrl": { "type": "string" }, "title": { "type": "string" }, "bio": { "type": "string" }, "username": { "type": "string" }, "displayName": { "type": "string" }, "newBio": { "type": "string" }, "newUsername": { "type": "string" }, "newDisplayName": { "type": "string" }, "videoId": { "type": "string" }, "profilePictureAvailable": { "type": "boolean" } } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string" }, "accountId": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "assigned", "in_progress", "pending_approval", "completed", "failed", "expired", "cancelled", "unknown" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ] }, "evidenceAvailable": { "type": "boolean" } }, "required": [ "taskId", "role", "accountId", "username", "status", "scheduledFor", "deadline", "startedAt", "submittedAt", "reviewedAt", "completedAt", "reason", "evidenceAvailable" ] } }, "currentAttemptId": { "type": "string" }, "availableActions": { "type": "array", "items": { "type": "string", "enum": [ "cancel", "resume" ] } }, "evidenceAvailable": { "type": "boolean" }, "credit": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "source": { "type": [ "string", "null" ] }, "outcome": { "type": "string", "enum": [ "reserved", "consumed", "refunded", "not_charged" ] } }, "required": [ "kind", "quantity", "source", "outcome" ] }, "historyComplete": { "type": "boolean" } }, "required": [ "taskId", "companyId", "type", "status", "accountId", "currentAccountId", "platform", "externalReference", "payload", "createdAt", "updatedAt", "completedAt", "reason", "components", "attempts", "currentAttemptId", "availableActions", "evidenceAvailable", "credit", "historyComplete" ] }, "example": { "taskId": "AMPLIFY_TASK_ID", "companyId": "COMPANY_ID", "type": "amplify_video", "status": "assigned", "accountId": "ACCOUNT_ID", "currentAccountId": "ACCOUNT_ID", "platform": "tiktok", "externalReference": "partner-order-123", "payload": { "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456", "commentText": "hi" }, "createdAt": "2027-01-01T00:00:00Z", "updatedAt": "2027-01-01T00:00:00Z", "completedAt": null, "reason": null, "components": [ { "taskId": "REPOST_LIKE_TASK_ID", "role": "repost_like", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false }, { "taskId": "COMMENT_TASK_ID", "role": "comment", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "attempts": [ { "taskId": "AMPLIFY_TASK_ID", "role": "attempt_1", "accountId": "ACCOUNT_ID", "username": "humanpost", "status": "assigned", "scheduledFor": null, "deadline": "2027-01-01T03:00:00Z", "startedAt": null, "submittedAt": null, "reviewedAt": null, "completedAt": null, "reason": null, "evidenceAvailable": false } ], "currentAttemptId": "AMPLIFY_TASK_ID", "availableActions": [ "cancel" ], "evidenceAvailable": false, "credit": { "kind": "amplify", "quantity": 1, "source": "monthly", "outcome": "reserved" }, "historyComplete": true } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/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 or MOV with H.264 or HEVC (H.265) video and AAC audio when present, no larger than 200 MB or 3 minutes, up to 2160 × 3840 and 60 fps. Supported uploads are stored without transcoding.", "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 or .mov extension." }, "contentType": { "type": "string", "minLength": 1, "maxLength": 100, "description": "For video uploads, use video/mp4 for MP4 or video/quicktime for MOV." }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "description": "Video uploads may be at most 209,715,200 bytes (200 MiB); images may be at most 52,428,800 bytes (50 MiB)." } }, "required": [ "kind", "filename", "contentType", "sizeBytes" ], "additionalProperties": false, "description": "For videos: MP4 or MOV, H.264 or HEVC (H.265) video, AAC audio when present, 200 MB maximum, 3 minutes maximum, up to 2160 × 3840, and 60 fps maximum. Supported uploads are stored without transcoding." }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "sourceUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "kind", "sourceUrl" ], "additionalProperties": false, "description": "Remote video uploads must resolve to an MP4 or MOV with H.264 or HEVC (H.265) video and AAC audio, no larger than 200 MB or 3 minutes, up to 2160 × 3840 and 60 fps. Supported uploads are stored without transcoding." } ] } } } }, "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" }, "requiredHeaders": { "type": "object", "properties": { "Content-Type": { "type": "string" } }, "required": [ "Content-Type" ] } }, "required": [ "uploadId", "uploadUrl", "expiresAt", "requiredHeaders" ] }, { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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", "null" ], "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/posts": { "post": { "summary": "Create and queue a post", "security": [ { "bearerAuth": [] } ], "description": "Optionally assign up to 10 tags or template reporting groups with contentGroupIds. Tags are for internal analytics and do not appear in the social caption.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Optional unique key for safe retries. Keep operation and payload unchanged; conflicting reuse returns 409. 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": 20 }, "accountIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 2, "description": "Choose at most one TikTok account and one Instagram account; duplicate platforms are rejected." }, "skipApproval": { "type": "boolean", "description": "When true, send the post directly to the posting queue instead of waiting for dashboard approval." }, "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", "description": "Earliest release instant, expressed as ISO 8601 with a timezone offset. Actual publishing follows worker-local windows and capacity; this is not an exact posting time." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Stop releasing queued targets at this instant. Does not recall work already released to an operator." }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "maxItems": 10, "description": "Optional tag or template reporting-group IDs. Use the contentGroupId returned by POST /v2/content-tags. Multiple groups are allowed; omit this field for no explicit tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ], "description": "How Instagram should publish the media. Regular posts require a company capability; Reels are the default." }, "slides": { "type": "array", "items": { "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 200 }, "textElements": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 500 }, "style": { "type": "object", "properties": { "backgroundColor": { "type": "string", "enum": [ "none", "black", "white", "red", "yellow", "blue" ], "default": "none" }, "textColor": { "type": "string", "enum": [ "white", "black", "red", "yellow", "blue" ], "default": "white" }, "fontSize": { "type": "number", "minimum": 6, "maximum": 72, "default": 16 }, "fontWeight": { "type": "string", "enum": [ "normal", "bold" ], "default": "normal" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ], "default": "center" }, "textMode": { "type": "string", "enum": [ "stroke", "background", "plain", "snapchat" ], "default": "stroke" }, "positionX": { "type": "number", "minimum": 0, "maximum": 100, "default": 50 }, "positionY": { "type": "number", "minimum": 0, "maximum": 100 }, "width": { "type": "number", "minimum": 20, "maximum": 100, "default": 88 }, "padding": { "type": "number", "minimum": 0, "maximum": 20, "default": 0 } }, "required": [ "positionY" ], "additionalProperties": false } }, "required": [ "content", "style" ], "additionalProperties": false }, "maxItems": 6 }, "imageFit": { "type": "string", "enum": [ "fit", "fill" ], "default": "fill" }, "role": { "type": "string", "enum": [ "hook", "middle", "cta" ] } }, "required": [ "image", "textElements" ], "additionalProperties": false }, "minItems": 2, "maxItems": 20 } }, "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } }, "get": { "summary": "List posts", "security": [ { "bearerAuth": [] } ], "description": "Optionally filter by one tag or template reporting group with contentGroupId, or use `untagged` to return posts with no attribution.", "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" }, { "schema": { "anyOf": [ { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, { "type": "string", "enum": [ "untagged" ] } ], "description": "Return only posts attributed to this tag or template reporting group. Use `untagged` for posts with no tag or template attribution." }, "required": false, "description": "Return only posts attributed to this tag or template reporting group. Use `untagged` for posts with no tag or template attribution.", "name": "contentGroupId", "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "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", "minLength": 1, "maxLength": 200, "description": "Optional unique key for safe retries. Keep operation and payload unchanged; conflicting reuse returns 409. 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": 2, "description": "Choose at most one TikTok account and one Instagram account; duplicate platforms are rejected." }, "skipApproval": { "type": "boolean", "description": "When true, send the post directly to the posting queue instead of waiting for dashboard approval." }, "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", "description": "Earliest release instant, expressed as ISO 8601 with a timezone offset. Actual publishing follows worker-local windows and capacity; this is not an exact posting time." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Stop releasing queued targets at this instant. Does not recall work already released to an operator." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ], "description": "How Instagram should publish the media. Regular posts require a company capability; Reels are the default." } }, "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } }, "patch": { "summary": "Update post metadata or content tags", "security": [ { "bearerAuth": [] } ], "description": "contentGroupIds replaces the complete explicit assignment list and can be changed before or after publishing. Resend the desired list to add or remove individual tags; send [] to remove all explicit tags. Other metadata remains subject to normal post editability rules.", "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 }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "maxItems": 10, "description": "Replace the post's complete list of explicitly assigned tag or template reporting groups. This remains editable after publishing. To remove one tag, resend the list without it; pass [] to remove every explicit tag. Template provenance inherited from the post's original template remains visible." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ], "description": "How Instagram should publish the media. `post` is rejected unless the company has regular feed posts enabled." } }, "additionalProperties": false }, "example": { "contentGroupIds": [ "tag:abc123", "tag:def456" ] } } } }, "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/content-tags": { "get": { "summary": "List content tags", "security": [ { "bearerAuth": [] } ], "description": "Returns active and archived custom tags with the stable contentGroupId value used when creating, updating, or filtering posts.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "tagId": { "type": "string" }, "contentGroupId": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$", "description": "Stable value to send in a post's contentGroupIds array, for example `tag:abc123`." }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "blue", "cyan", "green", "amber", "orange", "rose", "violet" ] }, "archived": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "tagId", "contentGroupId", "name", "color", "archived", "createdAt", "updatedAt" ] } } }, "required": [ "data" ] } } } } } }, "post": { "summary": "Create a content tag", "security": [ { "bearerAuth": [] } ], "description": "Creates an optional company-scoped analytics tag. Use the returned contentGroupId in a post's contentGroupIds array.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Unique tag name within the API key's company." }, "color": { "type": "string", "enum": [ "slate", "blue", "cyan", "green", "amber", "orange", "rose", "violet" ], "default": "slate", "description": "Dashboard display color. Defaults to slate." } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tagId": { "type": "string" }, "contentGroupId": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$", "description": "Stable value to send in a post's contentGroupIds array, for example `tag:abc123`." }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "blue", "cyan", "green", "amber", "orange", "rose", "violet" ] }, "archived": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "tagId", "contentGroupId", "name", "color", "archived", "createdAt", "updatedAt" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/content-tags/{tagId}": { "patch": { "summary": "Update or archive a content tag", "security": [ { "bearerAuth": [] } ], "description": "Rename or recolor a tag, archive it to prevent new assignments, or restore it with archived: false. Archiving preserves existing post attribution and analytics.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "tagId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "New unique tag name." }, "color": { "type": "string", "enum": [ "slate", "blue", "cyan", "green", "amber", "orange", "rose", "violet" ], "description": "New dashboard display color." }, "archived": { "type": "boolean", "description": "Set true to hide the tag from new assignments without changing historical attribution; set false to restore it." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tagId": { "type": "string" }, "contentGroupId": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$", "description": "Stable value to send in a post's contentGroupIds array, for example `tag:abc123`." }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "slate", "blue", "cyan", "green", "amber", "orange", "rose", "violet" ] }, "archived": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "tagId", "contentGroupId", "name", "color", "archived", "createdAt", "updatedAt" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } }, "delete": { "summary": "Delete a content tag", "security": [ { "bearerAuth": [] } ], "description": "Permanently deletes the tag and removes it from all posts in the company. Prefer archiving for historical continuity.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "tagId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tagId": { "type": "string" }, "updatedPosts": { "type": "integer" } }, "required": [ "tagId", "updatedPosts" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/schedule": { "get": { "summary": "Get the company posting schedule", "security": [ { "bearerAuth": [] } ], "description": "Requires accounts:read. Returns the default for the API key's company. Individual account overrides take precedence.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" }, "schedule": { "type": [ "object", "null" ], "properties": { "windows": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "minItems": 1, "maxItems": 4 } }, "required": [ "windows" ] }, "source": { "type": "string", "enum": [ "company", "global" ] }, "scheduledPostsPerDay": { "type": [ "integer", "null" ], "description": "Selected window count, or null when global gap-based rules apply." }, "maxPostsPerDay": { "type": "number", "enum": [ 4 ], "description": "Hard daily limit per account, including make-up posts." }, "timezoneMode": { "type": "string", "enum": [ "worker_local" ] } }, "required": [ "companyId", "schedule", "source", "scheduledPostsPerDay", "maxPostsPerDay", "timezoneMode" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } }, "patch": { "summary": "Set the company posting schedule", "security": [ { "bearerAuth": [] } ], "description": "Requires accounts:write. Replaces the company default, preserving individual account overrides. Individual account schedules still take priority even when this default is edited afterward through the dashboard, API, or MCP. One daily post per selected 3-hour window, in each assigned worker's local timezone. Send schedule: null to restore global rules, not pause posting. Applies to future dispatches; already released tasks are unchanged. Missed posts may use unused make-up windows, up to 4 posts/day/account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": [ "object", "null" ], "properties": { "windows": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "minItems": 1, "maxItems": 4 } }, "required": [ "windows" ], "description": "Replace the active windows with 1–4 sorted HH:mm starts, at least 3 hours apart, between 08:00 and 17:00 inclusive. Standard slots: 08:00, 11:00, 14:00, 17:00. Times follow each assigned worker's timezone. null clears the override; it does not pause posting." } }, "required": [ "schedule" ], "additionalProperties": false }, "example": { "schedule": { "windows": [ "08:00", "17:00" ] } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string" }, "schedule": { "type": [ "object", "null" ], "properties": { "windows": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "minItems": 1, "maxItems": 4 } }, "required": [ "windows" ] }, "source": { "type": "string", "enum": [ "company", "global" ] }, "scheduledPostsPerDay": { "type": [ "integer", "null" ], "description": "Selected window count, or null when global gap-based rules apply." }, "maxPostsPerDay": { "type": "number", "enum": [ 4 ], "description": "Hard daily limit per account, including make-up posts." }, "timezoneMode": { "type": "string", "enum": [ "worker_local" ] } }, "required": [ "companyId", "schedule", "source", "scheduledPostsPerDay", "maxPostsPerDay", "timezoneMode" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts/{accountId}/schedule": { "get": { "summary": "Get an account's effective posting schedule", "security": [ { "bearerAuth": [] } ], "description": "Requires accounts:read. Returns the account override, company default, effective schedule, source, and timezone. Account must belong to the API key's company.", "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" }, "schedule": { "type": [ "object", "null" ], "properties": { "windows": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "minItems": 1, "maxItems": 4 } }, "required": [ "windows" ], "description": "Account override; null means inherit." }, "companySchedule": { "type": [ "object", "null" ], "properties": { "windows": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "minItems": 1, "maxItems": 4 } }, "required": [ "windows" ] }, "effectiveSchedule": { "type": [ "object", "null" ], "properties": { "windows": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "minItems": 1, "maxItems": 4 } }, "required": [ "windows" ] }, "source": { "type": "string", "enum": [ "account", "company", "global" ] }, "scheduledPostsPerDay": { "type": [ "integer", "null" ] }, "maxPostsPerDay": { "type": "number", "enum": [ 4 ] }, "timezoneMode": { "type": "string", "enum": [ "worker_local" ] }, "timezone": { "type": "string" } }, "required": [ "accountId", "schedule", "companySchedule", "effectiveSchedule", "source", "scheduledPostsPerDay", "maxPostsPerDay", "timezoneMode", "timezone" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } }, "patch": { "summary": "Set or clear an account posting schedule", "security": [ { "bearerAuth": [] } ], "description": "Requires accounts:write. Replaces this account's override. Send schedule: null to inherit the company default (or global rules), not pause posting. Applies to future dispatches; already released tasks are unchanged. Times follow the assigned worker's timezone. Missed posts may use unused make-up windows, up to 4 posts/day.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "accountId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": [ "object", "null" ], "properties": { "windows": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "minItems": 1, "maxItems": 4 } }, "required": [ "windows" ], "description": "Replace the active windows with 1–4 sorted HH:mm starts, at least 3 hours apart, between 08:00 and 17:00 inclusive. Standard slots: 08:00, 11:00, 14:00, 17:00. Times follow each assigned worker's timezone. null clears the override; it does not pause posting." } }, "required": [ "schedule" ], "additionalProperties": false }, "example": { "schedule": { "windows": [ "11:00", "14:00" ] } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "schedule": { "type": [ "object", "null" ], "properties": { "windows": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "minItems": 1, "maxItems": 4 } }, "required": [ "windows" ], "description": "Account override; null means inherit." }, "companySchedule": { "type": [ "object", "null" ], "properties": { "windows": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "minItems": 1, "maxItems": 4 } }, "required": [ "windows" ] }, "effectiveSchedule": { "type": [ "object", "null" ], "properties": { "windows": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "minItems": 1, "maxItems": 4 } }, "required": [ "windows" ] }, "source": { "type": "string", "enum": [ "account", "company", "global" ] }, "scheduledPostsPerDay": { "type": [ "integer", "null" ] }, "maxPostsPerDay": { "type": "number", "enum": [ 4 ] }, "timezoneMode": { "type": "string", "enum": [ "worker_local" ] }, "timezone": { "type": "string" } }, "required": [ "accountId", "schedule", "companySchedule", "effectiveSchedule", "source", "scheduledPostsPerDay", "maxPostsPerDay", "timezoneMode", "timezone" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts": { "get": { "summary": "List publishing accounts", "security": [ { "bearerAuth": [] } ], "description": "Requires accounts:read. Returns only the API key's company accounts. Includes stored profilePictureUrl, bio, and warmupSearchTerms. Missing picture/bio values are null; missing terms are []. Setup placeholders contain requested values; pending profile edits retain previous values until worker approval. Stored values do not independently verify the live platform profile or completed warm-up.", "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" ] }, "profilePictureUrl": { "type": [ "string", "null" ], "description": "Stored profile picture URL (profilePicture, falling back to avatarUrl); null when absent. Setup placeholders contain requested values. This is not independent verification of the live platform profile." }, "bio": { "type": [ "string", "null" ], "description": "Stored account bio; null when absent and an empty string when explicitly stored empty. Setup placeholders contain requested values; pending profile edits retain the previous value until worker approval." }, "warmupSearchTerms": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "description": "Stored account-specific warm-up search terms, normalized to strings; [] when absent. Historical lists may exceed the five-term creation limit. These terms do not verify completed warm-up activity." }, "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", "profilePictureUrl", "bio", "warmupSearchTerms", "status", "timezone", "followers", "postsToday", "dailyCap", "queueDepth", "nextWindow", "lastPostAt" ] } } }, "required": [ "data" ] }, "example": { "data": [ { "accountId": "ACCOUNT_ID", "platform": "tiktok", "username": "buildmode", "displayName": "Build Mode", "profilePictureUrl": "https://cdn.example.com/build-mode.png", "bio": "Building practical side hustles in public.", "warmupSearchTerms": [ "build in public", "side hustle experiments" ], "status": "settingUp", "timezone": "America/New_York", "followers": 0, "postsToday": 0, "dailyCap": 4, "queueDepth": 0, "nextWindow": null, "lastPostAt": null } ] } } } } } }, "post": { "summary": "Create a publishing account", "security": [ { "bearerAuth": [] } ], "description": "Provide 1–5 warmup.searchTerms. Requests with more than five terms are rejected. Existing accounts and tasks with longer lists remain supported; new or edited lists must have at most five terms. The response uses warmupSearchTerms for the stored terms. Account setup is asynchronous. Includes stored profilePictureUrl, bio, and warmupSearchTerms. Missing picture/bio values are null; missing terms are []. Setup placeholders contain requested values; pending profile edits retain previous values until worker approval. Stored values do not independently verify the live platform profile or completed warm-up.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "username": { "type": "string", "pattern": "^[a-z0-9_.]{1,30}$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "bio": { "type": "string", "minLength": 1, "maxLength": 220 }, "profilePictureUrl": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Use the stable URL from a completed image upload (POST /v2/uploads, then GET /v2/uploads/{uploadId}.url). Compatible direct HTTP(S) image URLs are decoded and copied into owned Storage. JPEG, PNG, WebP or GIF; maximum 10 MB and 40 megapixels. Drive viewer/HTML pages are rejected." }, "bioUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "warmup": { "type": "object", "properties": { "searchTerms": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 1, "maxItems": 5, "description": "1–5 account-specific warm-up search terms. Existing accounts may contain more than five." } }, "required": [ "searchTerms" ], "additionalProperties": false } }, "required": [ "platform", "username", "displayName", "bio", "profilePictureUrl", "warmup" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Setup requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "username": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "profilePictureUrl": { "type": [ "string", "null" ], "description": "Stored profile picture URL (profilePicture, falling back to avatarUrl); null when absent. Setup placeholders contain requested values. This is not independent verification of the live platform profile." }, "bio": { "type": [ "string", "null" ], "description": "Stored account bio; null when absent and an empty string when explicitly stored empty. Setup placeholders contain requested values; pending profile edits retain the previous value until worker approval." }, "warmupSearchTerms": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "description": "Stored account-specific warm-up search terms, normalized to strings; [] when absent. Historical lists may exceed the five-term creation limit. These terms do not verify completed warm-up activity." }, "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", "profilePictureUrl", "bio", "warmupSearchTerms", "status", "timezone", "followers", "postsToday", "dailyCap", "queueDepth", "nextWindow", "lastPostAt" ] }, "example": { "accountId": "ACCOUNT_ID", "platform": "tiktok", "username": "buildmode", "displayName": "Build Mode", "profilePictureUrl": "https://cdn.example.com/build-mode.png", "bio": "Building practical side hustles in public.", "warmupSearchTerms": [ "build in public", "side hustle experiments" ], "status": "settingUp", "timezone": "America/New_York", "followers": 0, "postsToday": 0, "dailyCap": 4, "queueDepth": 0, "nextWindow": null, "lastPostAt": null } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts/{accountId}": { "get": { "summary": "Get a publishing account", "security": [ { "bearerAuth": [] } ], "description": "Requires accounts:read. Account must belong to the API key's company. Includes stored profilePictureUrl, bio, and warmupSearchTerms. Missing picture/bio values are null; missing terms are []. Setup placeholders contain requested values; pending profile edits retain previous values until worker approval. Stored values do not independently verify the live platform profile or completed warm-up.", "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" ] }, "profilePictureUrl": { "type": [ "string", "null" ], "description": "Stored profile picture URL (profilePicture, falling back to avatarUrl); null when absent. Setup placeholders contain requested values. This is not independent verification of the live platform profile." }, "bio": { "type": [ "string", "null" ], "description": "Stored account bio; null when absent and an empty string when explicitly stored empty. Setup placeholders contain requested values; pending profile edits retain the previous value until worker approval." }, "warmupSearchTerms": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "description": "Stored account-specific warm-up search terms, normalized to strings; [] when absent. Historical lists may exceed the five-term creation limit. These terms do not verify completed warm-up activity." }, "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", "profilePictureUrl", "bio", "warmupSearchTerms", "status", "timezone", "followers", "postsToday", "dailyCap", "queueDepth", "nextWindow", "lastPostAt" ] }, "example": { "accountId": "ACCOUNT_ID", "platform": "tiktok", "username": "buildmode", "displayName": "Build Mode", "profilePictureUrl": "https://cdn.example.com/build-mode.png", "bio": "Building practical side hustles in public.", "warmupSearchTerms": [ "build in public", "side hustle experiments" ], "status": "settingUp", "timezone": "America/New_York", "followers": 0, "postsToday": 0, "dailyCap": 4, "queueDepth": 0, "nextWindow": null, "lastPostAt": null } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts/{accountId}/profile-changes": { "post": { "summary": "Request existing-account profile updates", "security": [ { "bearerAuth": [] } ], "description": "Requires accounts:write. Groups username, display name, bio and picture edits into the existing asynchronous worker workflow. Two fully completed requests per account in a rolling 30-day window are included; partial/failed requests do not consume this allowance. Only one request may be active. Platform restrictions also apply. Reuse the same key and body to retry, including after completion or interrupted task dispatch.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "accountId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Required stable key, scoped to company and account. Conflicting reuse returns 409." }, "required": true, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Username; leading @ is removed and letters are lowercased. 1–30 letters, numbers, periods or underscores; no trailing period. Platform availability is checked by the worker." }, "displayName": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Display name: up to 30 characters for TikTok or 50 for Instagram." }, "bio": { "type": "string", "maxLength": 150, "description": "Bio: up to 80 characters for TikTok or 150 for Instagram. Empty string clears the bio." }, "profilePictureUploadId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A ready image upload belonging to this company. Profile photos must decode as JPEG, PNG, WebP or GIF, at most 10 MB and 40 megapixels. Upload through /v2/uploads first; arbitrary image URLs and signed PUT URLs are not accepted here." } }, "additionalProperties": false }, "example": { "displayName": "Build Mode", "bio": "Tools for growing teams", "profilePictureUploadId": "upload_123" } } } }, "responses": { "200": { "description": "Original request returned on idempotent replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "creating", "queued", "in_progress", "pending_approval", "completed", "partially_completed", "blocked", "failed" ] }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "completedFields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "blockedFields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "allowance": { "type": "object", "properties": { "limit": { "type": "number", "enum": [ 2 ] }, "windowDays": { "type": "number", "enum": [ 30 ] }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "nextEligibleAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "limit", "windowDays", "used", "remaining", "nextEligibleAt" ] }, "idempotentReplay": { "type": "boolean" } }, "required": [ "requestId", "accountId", "status", "fields", "completedFields", "blockedFields", "message", "createdAt", "updatedAt", "completedAt", "allowance", "idempotentReplay" ] }, "example": { "requestId": "profile_123", "accountId": "account_123", "status": "queued", "fields": [ "displayName", "bio", "profilePicture" ], "completedFields": [], "blockedFields": [], "message": null, "createdAt": "2026-10-09T12:00:00.000Z", "updatedAt": "2026-10-09T12:00:00.000Z", "completedAt": null, "allowance": { "limit": 2, "windowDays": 30, "used": 0, "remaining": 2, "nextEligibleAt": null }, "idempotentReplay": true } } } }, "202": { "description": "Accepted; worker execution and approval are pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "creating", "queued", "in_progress", "pending_approval", "completed", "partially_completed", "blocked", "failed" ] }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "completedFields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "blockedFields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "allowance": { "type": "object", "properties": { "limit": { "type": "number", "enum": [ 2 ] }, "windowDays": { "type": "number", "enum": [ 30 ] }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "nextEligibleAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "limit", "windowDays", "used", "remaining", "nextEligibleAt" ] }, "idempotentReplay": { "type": "boolean" } }, "required": [ "requestId", "accountId", "status", "fields", "completedFields", "blockedFields", "message", "createdAt", "updatedAt", "completedAt", "allowance", "idempotentReplay" ] }, "example": { "requestId": "profile_123", "accountId": "account_123", "status": "queued", "fields": [ "displayName", "bio", "profilePicture" ], "completedFields": [], "blockedFields": [], "message": null, "createdAt": "2026-10-09T12:00:00.000Z", "updatedAt": "2026-10-09T12:00:00.000Z", "completedAt": null, "allowance": { "limit": 2, "windowDays": 30, "used": 0, "remaining": 2, "nextEligibleAt": null }, "idempotentReplay": false } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } }, "get": { "summary": "Get profile-update eligibility and latest request", "security": [ { "bearerAuth": [] } ], "description": "Requires accounts:read. Returns allowance, field eligibility, active request and latest outcome. Instagram name dates follow HumanPost's rolling 14-day safeguard; the platform limit and reset semantics are unverified. Dates do not guarantee platform acceptance, and outside edits may be unknown. Null means no tracked restriction, not unlimited edits. Check fieldNextEligibleAt as well as canSubmit.", "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" }, "allowance": { "type": "object", "properties": { "limit": { "type": "number", "enum": [ 2 ] }, "windowDays": { "type": "number", "enum": [ 30 ] }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "nextEligibleAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "limit", "windowDays", "used", "remaining", "nextEligibleAt" ] }, "fieldNextEligibleAt": { "type": "object", "properties": { "username": { "type": [ "string", "null" ], "format": "date-time" }, "displayName": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": [ "string", "null" ], "format": "date-time" }, "profilePicture": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "username", "displayName", "bio", "profilePicture" ], "description": "HumanPost request eligibility dates based on recorded edits and safeguards. Instagram name dates use HumanPost's rolling 14-day safeguard; the platform limit and reset semantics are unverified. Dates do not guarantee platform acceptance; outside edits may be unknown." }, "activeRequestId": { "type": [ "string", "null" ] }, "legacyRequestPending": { "type": "boolean" }, "canSubmit": { "type": "boolean", "description": "General account/allowance eligibility. Check fieldNextEligibleAt for the fields you intend to change. Platform restrictions may still block execution." }, "nextEligibleAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest allowance reset, or null when available/unknown. A running request or platform restriction can delay submission further." }, "latestRequest": { "type": [ "object", "null" ], "properties": { "requestId": { "type": "string" }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "creating", "queued", "in_progress", "pending_approval", "completed", "partially_completed", "blocked", "failed" ] }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "completedFields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "blockedFields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "allowance": { "type": "object", "properties": { "limit": { "type": "number", "enum": [ 2 ] }, "windowDays": { "type": "number", "enum": [ 30 ] }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "nextEligibleAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "limit", "windowDays", "used", "remaining", "nextEligibleAt" ] }, "idempotentReplay": { "type": "boolean" } }, "required": [ "requestId", "accountId", "status", "fields", "completedFields", "blockedFields", "message", "createdAt", "updatedAt", "completedAt", "allowance", "idempotentReplay" ] } }, "required": [ "accountId", "allowance", "fieldNextEligibleAt", "activeRequestId", "legacyRequestPending", "canSubmit", "nextEligibleAt", "latestRequest" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts/{accountId}/profile-changes/{profileChangeRequestId}": { "get": { "summary": "Get a profile-update request", "security": [ { "bearerAuth": [] } ], "description": "Requires accounts:read. Poll status and inspect completedFields, blockedFields and message. completed means every field was approved; partially_completed, blocked and failed are terminal. Stored account values update through existing worker approval behavior.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "accountId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "profileChangeRequestId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "creating", "queued", "in_progress", "pending_approval", "completed", "partially_completed", "blocked", "failed" ] }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "completedFields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "blockedFields": { "type": "array", "items": { "type": "string", "enum": [ "username", "displayName", "bio", "profilePicture" ] } }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "allowance": { "type": "object", "properties": { "limit": { "type": "number", "enum": [ 2 ] }, "windowDays": { "type": "number", "enum": [ 30 ] }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "nextEligibleAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "limit", "windowDays", "used", "remaining", "nextEligibleAt" ] }, "idempotentReplay": { "type": "boolean" } }, "required": [ "requestId", "accountId", "status", "fields", "completedFields", "blockedFields", "message", "createdAt", "updatedAt", "completedAt", "allowance", "idempotentReplay" ] }, "example": { "requestId": "profile_123", "accountId": "account_123", "status": "queued", "fields": [ "displayName", "bio", "profilePicture" ], "completedFields": [], "blockedFields": [], "message": null, "createdAt": "2026-10-09T12:00:00.000Z", "updatedAt": "2026-10-09T12:00:00.000Z", "completedAt": null, "allowance": { "limit": 2, "windowDays": 30, "used": 0, "remaining": 2, "nextEligibleAt": null }, "idempotentReplay": false } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "scheduledAfter": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledSlotStart": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "postId", "queueItemId", "status", "caption", "thumbnailUrl", "queuedAt", "scheduledAfter", "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" }, "coverage": { "type": "object", "properties": { "limit": { "type": "number", "enum": [ 200 ] }, "possiblyTruncated": { "type": "boolean" }, "source": { "type": "string" }, "destinationSpecific": { "type": "boolean", "enum": [ false ] }, "latestCollectedAt": { "type": [ "string", "null" ] } }, "required": [ "limit", "possiblyTruncated", "source", "destinationSpecific", "latestCollectedAt" ] } }, "required": [ "accountId", "followers", "posts", "engagement", "analytics", "scannedPosts", "coverage" ] } } } } } } }, "/v2/usage": { "get": { "summary": "Get plan and API usage", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskCredits": { "type": "object", "properties": { "comment": { "type": "object", "properties": { "monthlyLimit": { "type": "number" }, "monthlyUsed": { "type": "number" }, "monthlyAvailable": { "type": "number" }, "oneTimeAvailable": { "type": "number" }, "totalAvailable": { "type": "number" }, "monthlyCreditsAvailable": { "type": "boolean" } }, "required": [ "monthlyLimit", "monthlyUsed", "monthlyAvailable", "oneTimeAvailable", "totalAvailable", "monthlyCreditsAvailable" ] }, "amplify": { "type": "object", "properties": { "monthlyLimit": { "type": "number" }, "monthlyUsed": { "type": "number" }, "monthlyAvailable": { "type": "number" }, "oneTimeAvailable": { "type": "number" }, "totalAvailable": { "type": "number" }, "monthlyCreditsAvailable": { "type": "boolean" } }, "required": [ "monthlyLimit", "monthlyUsed", "monthlyAvailable", "oneTimeAvailable", "totalAvailable", "monthlyCreditsAvailable" ] }, "periodStart": { "type": [ "string", "null" ], "format": "date-time" }, "periodEnd": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "comment", "amplify", "periodStart", "periodEnd" ] }, "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" }, "uploadsCreatedToday": { "type": "number" }, "accountsCreatedToday": { "type": "number" }, "dailyLimits": { "type": "object", "properties": { "apiRequestsToday": { "type": "number" }, "postsCreatedToday": { "type": "number" }, "uploadsCreatedToday": { "type": "number" }, "accountsCreatedToday": { "type": "number" } }, "required": [ "apiRequestsToday", "postsCreatedToday", "uploadsCreatedToday", "accountsCreatedToday" ] }, "resetsAt": { "type": "string", "format": "date-time" } }, "required": [ "plan", "billingType", "videoQuota", "videoCount", "postCredits", "postsPerDay", "apiRequestsToday", "postsCreatedToday", "uploadsCreatedToday", "accountsCreatedToday", "dailyLimits", "resetsAt" ] } } } } } } }, "/v2/workspace": { "get": { "summary": "Read a company workspace", "security": [ { "bearerAuth": [] } ], "description": "Returns only the company bound to the API key, its connected accounts, and sanitized image folder and pack metadata. Requires workspace:read.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "company": { "type": "object", "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string" } }, "required": [ "companyId", "name" ] }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "username": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "profilePictureUrl": { "type": [ "string", "null" ], "description": "Stored profile picture URL (profilePicture, falling back to avatarUrl); null when absent. Setup placeholders contain requested values. This is not independent verification of the live platform profile." }, "bio": { "type": [ "string", "null" ], "description": "Stored account bio; null when absent and an empty string when explicitly stored empty. Setup placeholders contain requested values; pending profile edits retain the previous value until worker approval." }, "warmupSearchTerms": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "description": "Stored account-specific warm-up search terms, normalized to strings; [] when absent. Historical lists may exceed the five-term creation limit. These terms do not verify completed warm-up activity." }, "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" }, "niche": { "type": "string", "maxLength": 160 } }, "required": [ "accountId", "platform", "username", "displayName", "profilePictureUrl", "bio", "warmupSearchTerms", "status", "timezone", "followers", "postsToday", "dailyCap", "queueDepth", "nextWindow", "lastPostAt" ] } }, "folders": { "type": "array", "items": { "type": "object", "properties": { "folderId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "images": { "type": "array", "items": { "type": "object", "properties": { "imageId": { "type": "string" }, "folderId": { "type": "string" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "width": { "type": [ "number", "null" ] }, "height": { "type": [ "number", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "imageId", "folderId", "label", "description", "tags", "width", "height", "createdAt" ] } }, "packs": { "type": "array", "items": { "type": "object", "properties": { "packId": { "type": "string" }, "folderId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "imageIds": { "type": "array", "items": { "type": "string" } }, "imageFit": { "type": [ "string", "null" ], "enum": [ "fit", "fill" ] }, "useImagesOnce": { "type": "boolean" } }, "required": [ "packId", "folderId", "name", "description", "color", "imageIds", "imageFit", "useImagesOnce" ] } } }, "required": [ "folderId", "name", "createdAt", "images", "packs" ] } }, "refreshedAt": { "type": "string", "format": "date-time" } }, "required": [ "version", "company", "accounts", "folders", "refreshedAt" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/workspace/media-urls": { "post": { "summary": "Create short-lived image download URLs", "security": [ { "bearerAuth": [] } ], "description": "Resolves selected images through company-owned folder records before signing. Storage paths and credentials are never accepted from the caller. Requires media:read.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "folderId": { "type": "string", "minLength": 1, "maxLength": 200 }, "imageId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "folderId", "imageId" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "expiresInSeconds": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 900 } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresAt": { "type": "string", "format": "date-time" }, "data": { "type": "array", "items": { "type": "object", "properties": { "folderId": { "type": "string" }, "imageId": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "folderId", "imageId", "url" ] } } }, "required": [ "expiresAt", "data" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/context": { "get": { "summary": "Read company, scopes, and capabilities", "security": [ { "bearerAuth": [] } ], "description": "Confirms the company bound to this key, granted scopes, available tools and capabilities.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "object", "properties": { "companyId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "companyId", "name" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "posts:read", "posts:write", "accounts:read", "accounts:write", "analytics:read", "usage:read", "workspace:read", "media:read", "tasks:read", "tasks:write", "tasks:evidence:read" ] } }, "availableTools": { "type": "array", "items": { "type": "string" } }, "capabilities": { "type": "object", "properties": { "instagramFeedPosts": { "type": "boolean" }, "maxAccountsPerPost": { "type": "number", "enum": [ 2 ] }, "oneAccountPerPlatform": { "type": "boolean", "enum": [ true ] }, "maxCarouselImages": { "type": "number", "enum": [ 20 ] }, "scheduling": { "type": "string", "enum": [ "earliest_release_worker_local" ] }, "taskTypes": { "type": "array", "items": { "type": "string" } }, "taskReview": { "type": "string", "enum": [ "humanpost" ] } }, "required": [ "instagramFeedPosts", "maxAccountsPerPost", "oneAccountPerPlatform", "maxCarouselImages", "scheduling" ] }, "serverVersion": { "type": "string" } }, "required": [ "company", "scopes", "availableTools", "capabilities", "serverVersion" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/uploads/batch": { "post": { "summary": "Import an ordered resumable URL batch", "security": [ { "bearerAuth": [] } ], "description": "Requires posts:write. Imports 1–100 public URLs durably; job results retain input indices and per-file failures. Poll /v2/jobs/{jobId}. Reuse a key only with identical input.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409." }, "required": false, "description": "Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "sourceUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "kind", "sourceUrl" ], "additionalProperties": false, "description": "Remote video uploads must resolve to an MP4 or MOV with H.264 or HEVC (H.265) video and AAC audio, no larger than 200 MB or 3 minutes, up to 2160 × 3840 and 60 fps. Supported uploads are stored without transcoding." }, "minItems": 1, "maxItems": 100 } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "type": { "type": "string", "enum": [ "upload_batch", "preview", "analytics_report" ] }, "status": { "type": "string", "enum": [ "pending", "running", "complete", "partially_failed", "failed" ] }, "progress": { "type": "integer", "minimum": 0 }, "total": { "type": [ "integer", "null" ], "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "failed" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "index", "status" ] } }, "report": { "type": "object", "additionalProperties": {} }, "preview": { "type": "object", "properties": { "postId": { "type": "string" }, "versionId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "pending", "failed", "stale" ] }, "mediaUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "jobId": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "postId", "versionId", "status", "mediaUrls" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "jobId", "type", "status", "progress", "total", "createdAt", "updatedAt" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/jobs/{jobId}": { "get": { "summary": "Read job progress and results", "security": [ { "bearerAuth": [] } ], "description": "Requires analytics:read for reports; posts:write for previews/imports. Poll persisted progress or read final ordered results, preview URLs, or report. Requires the job's scope and the same company.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "jobId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "type": { "type": "string", "enum": [ "upload_batch", "preview", "analytics_report" ] }, "status": { "type": "string", "enum": [ "pending", "running", "complete", "partially_failed", "failed" ] }, "progress": { "type": "integer", "minimum": 0 }, "total": { "type": [ "integer", "null" ], "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "failed" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "index", "status" ] } }, "report": { "type": "object", "additionalProperties": {} }, "preview": { "type": "object", "properties": { "postId": { "type": "string" }, "versionId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "pending", "failed", "stale" ] }, "mediaUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "jobId": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "postId", "versionId", "status", "mediaUrls" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "jobId", "type", "status", "progress", "total", "createdAt", "updatedAt" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/analytics/reports": { "post": { "summary": "Compare UTC-day growth and rank observed destinations", "security": [ { "bearerAuth": [] } ], "description": "Requires analytics:read. Requires ready V3 rollups. Dates must be UTC midnight: from inclusive, to exclusive, maximum 366 days; previous period has equal duration. Growth follows collection dates. Top posts use latest cumulative views for destinations whose collection spans overlap the period. Includes freshness/coverage and up to 500 groups; tag groups overlap. Poll the returned job.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409." }, "required": false, "description": "Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "comparePrevious": { "type": "boolean", "default": true }, "accountId": { "type": "string", "minLength": 1, "maxLength": 200 }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "contentGroupId": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "groupBy": { "type": "string", "enum": [ "account", "platform", "content_group", "template" ], "default": "account" }, "topLimit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "type": { "type": "string", "enum": [ "upload_batch", "preview", "analytics_report" ] }, "status": { "type": "string", "enum": [ "pending", "running", "complete", "partially_failed", "failed" ] }, "progress": { "type": "integer", "minimum": 0 }, "total": { "type": [ "integer", "null" ], "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "failed" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "index", "status" ] } }, "report": { "type": "object", "additionalProperties": {} }, "preview": { "type": "object", "properties": { "postId": { "type": "string" }, "versionId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "pending", "failed", "stale" ] }, "mediaUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "jobId": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "postId", "versionId", "status", "mediaUrls" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "jobId", "type", "status", "progress", "total", "createdAt", "updatedAt" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/drafts": { "post": { "summary": "Create an unqueued editable draft", "security": [ { "bearerAuth": [] } ], "description": "Requires posts:write. Creates an unqueued draft. Optional slides retain editable text and styles; finished artwork can be used as-is. Posting billing is enforced on submission. Preview before queueing; draft creation counts once toward the post creation cap.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409." }, "required": false, "description": "Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.", "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": 20 }, "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 }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "maxItems": 10, "description": "Optional tag or template reporting-group IDs. Use the contentGroupId returned by POST /v2/content-tags. Multiple groups are allowed; omit this field for no explicit tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ], "description": "How Instagram should publish the media. Regular posts require a company capability; Reels are the default." }, "slides": { "type": "array", "items": { "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 200 }, "textElements": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 500 }, "style": { "type": "object", "properties": { "backgroundColor": { "type": "string", "enum": [ "none", "black", "white", "red", "yellow", "blue" ], "default": "none" }, "textColor": { "type": "string", "enum": [ "white", "black", "red", "yellow", "blue" ], "default": "white" }, "fontSize": { "type": "number", "minimum": 6, "maximum": 72, "default": 16 }, "fontWeight": { "type": "string", "enum": [ "normal", "bold" ], "default": "normal" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ], "default": "center" }, "textMode": { "type": "string", "enum": [ "stroke", "background", "plain", "snapchat" ], "default": "stroke" }, "positionX": { "type": "number", "minimum": 0, "maximum": 100, "default": 50 }, "positionY": { "type": "number", "minimum": 0, "maximum": 100 }, "width": { "type": "number", "minimum": 20, "maximum": 100, "default": 88 }, "padding": { "type": "number", "minimum": 0, "maximum": 20, "default": 0 } }, "required": [ "positionY" ], "additionalProperties": false } }, "required": [ "content", "style" ], "additionalProperties": false }, "maxItems": 6 }, "imageFit": { "type": "string", "enum": [ "fit", "fill" ], "default": "fill" }, "role": { "type": "string", "enum": [ "hook", "middle", "cta" ] } }, "required": [ "image", "textElements" ], "additionalProperties": false }, "minItems": 2, "maxItems": 20 } }, "required": [ "media" ], "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "createdAt", "accounts" ] } } } }, "201": { "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/drafts/{postId}": { "patch": { "summary": "Edit draft artwork or metadata with version conflict protection", "security": [ { "bearerAuth": [] } ], "description": "Requires posts:write. Edits only an unqueued draft. expectedVersionId prevents overwriting newer artwork. Replacing slides invalidates the preview; request a new preview before submission.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "postId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 20 }, "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 }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "maxItems": 10, "description": "Optional tag or template reporting-group IDs. Use the contentGroupId returned by POST /v2/content-tags. Multiple groups are allowed; omit this field for no explicit tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ], "description": "How Instagram should publish the media. Regular posts require a company capability; Reels are the default." }, "slides": { "type": "array", "items": { "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 200 }, "textElements": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 500 }, "style": { "type": "object", "properties": { "backgroundColor": { "type": "string", "enum": [ "none", "black", "white", "red", "yellow", "blue" ], "default": "none" }, "textColor": { "type": "string", "enum": [ "white", "black", "red", "yellow", "blue" ], "default": "white" }, "fontSize": { "type": "number", "minimum": 6, "maximum": 72, "default": 16 }, "fontWeight": { "type": "string", "enum": [ "normal", "bold" ], "default": "normal" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ], "default": "center" }, "textMode": { "type": "string", "enum": [ "stroke", "background", "plain", "snapchat" ], "default": "stroke" }, "positionX": { "type": "number", "minimum": 0, "maximum": 100, "default": 50 }, "positionY": { "type": "number", "minimum": 0, "maximum": 100 }, "width": { "type": "number", "minimum": 20, "maximum": 100, "default": 88 }, "padding": { "type": "number", "minimum": 0, "maximum": 20, "default": 0 } }, "required": [ "positionY" ], "additionalProperties": false } }, "required": [ "content", "style" ], "additionalProperties": false }, "maxItems": 6 }, "imageFit": { "type": "string", "enum": [ "fit", "fill" ], "default": "fill" }, "role": { "type": "string", "enum": [ "hook", "middle", "cta" ] } }, "required": [ "image", "textElements" ], "additionalProperties": false }, "minItems": 2, "maxItems": 20 }, "expectedVersionId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Reject a stale artwork edit rather than overwriting another editor's version." } }, "additionalProperties": false, "example": { "caption": "Updated draft caption", "expectedVersionId": "VERSION_ID" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "createdAt", "accounts" ] }, "versionId": { "type": [ "string", "null" ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "uploadId": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "required": [ "uploadId", "url" ] } }, "slides": { "type": "array", "items": { "type": "object", "properties": { "slideId": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "textElements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "style": { "type": "object", "additionalProperties": {} } }, "required": [ "content", "style" ] } }, "imageFit": { "type": "string", "enum": [ "fit", "fill" ] }, "role": { "type": "string" } }, "required": [ "slideId", "image", "imageUrl", "textElements", "imageFit" ] } } }, "required": [ "post", "versionId", "media", "slides" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/posts/{postId}/content": { "get": { "summary": "Read media, slide text, styles, and version", "security": [ { "bearerAuth": [] } ], "description": "Requires posts:read. Returns slide text/styles, upload IDs, signed background URLs (15 minutes), and the current versionId.", "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": { "post": { "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" ] }, "contentGroupIds": { "type": "array", "items": { "type": "string", "maxLength": 240, "pattern": "^(template|tag):[^:]+$" }, "description": "All reporting groups attributed to the post, including its implicit template provenance and any explicitly assigned tags." }, "instagramPostFormat": { "type": "string", "enum": [ "reel", "post" ] }, "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" }, "scheduledAfter": { "type": "string", "format": "date-time", "description": "Earliest release instant. Actual dispatch still follows the account schedule and worker availability." }, "expiresAt": { "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", "contentGroupIds", "instagramPostFormat", "createdAt", "accounts" ] }, "versionId": { "type": [ "string", "null" ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "uploadId": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "required": [ "uploadId", "url" ] } }, "slides": { "type": "array", "items": { "type": "object", "properties": { "slideId": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "textElements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "style": { "type": "object", "additionalProperties": {} } }, "required": [ "content", "style" ] } }, "imageFit": { "type": "string", "enum": [ "fit", "fill" ] }, "role": { "type": "string" } }, "required": [ "slideId", "image", "imageUrl", "textElements", "imageFit" ] } } }, "required": [ "post", "versionId", "media", "slides" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/posts/{postId}/preview": { "post": { "summary": "Render current draft without approving or submitting it", "security": [ { "bearerAuth": [] } ], "description": "Requires posts:write. Reads or requests the current draft preview. Rendering is asynchronous and does not approve or queue the draft. Old renders cannot replace newer versions.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "postId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409." }, "required": false, "description": "Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.", "name": "Idempotency-Key", "in": "header" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "type": { "type": "string", "enum": [ "upload_batch", "preview", "analytics_report" ] }, "status": { "type": "string", "enum": [ "pending", "running", "complete", "partially_failed", "failed" ] }, "progress": { "type": "integer", "minimum": 0 }, "total": { "type": [ "integer", "null" ], "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "failed" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "index", "status" ] } }, "report": { "type": "object", "additionalProperties": {} }, "preview": { "type": "object", "properties": { "postId": { "type": "string" }, "versionId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "pending", "failed", "stale" ] }, "mediaUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "jobId": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "postId", "versionId", "status", "mediaUrls" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "jobId", "type", "status", "progress", "total", "createdAt", "updatedAt" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } }, "get": { "summary": "Read current rendered preview", "security": [ { "bearerAuth": [] } ], "description": "Requires posts:read. Reads or requests the current draft preview. Rendering is asynchronous and does not approve or queue the draft. Old renders cannot replace newer versions.", "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" }, "versionId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "pending", "failed", "stale" ] }, "mediaUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "jobId": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "postId", "versionId", "status", "mediaUrls" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/workspace/folders": { "get": { "summary": "Browse company folders with bounded search and cursor", "security": [ { "bearerAuth": [] } ], "description": "Requires workspace:read. Browse company-owned folders with optional search. Scans are bounded; continue with nextCursor even if a filtered page is empty.", "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": 100 }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "folderId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "folderId", "name", "createdAt" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } }, "/v2/workspace/folders/{folderId}/images": { "get": { "summary": "Browse company-owned folder images", "security": [ { "bearerAuth": [] } ], "description": "Requires workspace:read. Browse available images in a company-owned folder with optional label, description, or tag search. Continue with nextCursor even if a filtered page is empty.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "folderId", "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" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "imageId": { "type": "string" }, "folderId": { "type": "string" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "width": { "type": [ "number", "null" ] }, "height": { "type": [ "number", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "imageId", "folderId", "label", "description", "tags", "width", "height", "createdAt" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ] } } } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } }, "503": { "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" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "retryAfterSeconds": { "type": "number", "minimum": 0 }, "context": { "type": "object", "additionalProperties": {}, "description": "Operation-specific context, including profile-change allowance, active request and retryAt when applicable." } }, "required": [ "code", "message", "requestId", "retryable" ] } }, "required": [ "error" ] } } } } } } } }, "webhooks": {} }