{ "openapi": "3.1.0", "info": { "title": "HumanPost Publishing API", "version": "2.2.0", "description": "Server-to-server publishing, content tagging, accounts, queues, analytics, and company-scoped 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/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", "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" } }, "required": [ "uploadId", "uploadUrl", "expiresAt" ] }, { "type": "object", "properties": { "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready" ] } }, "required": [ "uploadId", "status" ] } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "415": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/uploads/{uploadId}/complete": { "post": { "summary": "Complete a signed upload", "security": [ { "bearerAuth": [] } ], "description": "Validates uploaded video container, codecs, size, duration, dimensions, and frame rate before marking it ready.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "uploadId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "ready" ] } }, "required": [ "uploadId", "status" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "413": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "415": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/uploads/{uploadId}": { "get": { "summary": "Get upload status", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "uploadId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string" }, "kind": { "type": "string", "enum": [ "video", "image" ] }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ] }, "url": { "type": "string", "format": "uri" }, "thumbnailUrl": { "type": "string", "format": "uri" }, "error": { "type": "string" } }, "required": [ "uploadId", "kind", "status" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/posts": { "post": { "summary": "Create and queue a post", "security": [ { "bearerAuth": [] } ], "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", "maxLength": 200, "description": "Optional unique key for safe retries. Repeating a request with the same key returns the original post (HTTP 200) instead of creating a duplicate." }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 10 }, "accountIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 50 }, "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 }, "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": 10 } }, "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": "Legacy earliest-release floor, returned only when an existing queue item already has one." }, "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": "Legacy earliest-release floor, returned only when an existing queue item already has one." }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } }, "get": { "summary": "List posts", "security": [ { "bearerAuth": [] } ], "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": "Legacy earliest-release floor, returned only when an existing queue item already has one." }, "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", "maxLength": 200, "description": "Optional unique key for safe retries. Repeating a request with the same key returns the original post (HTTP 200) instead of adding duplicate queue items." }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 50 }, "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 }, "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": "Legacy earliest-release floor, returned only when an existing queue item already has one." }, "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": "Legacy earliest-release floor, returned only when an existing queue item already has one." }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Conflict (`media_not_ready`, `duplicate_queue_item`, or post already published)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/posts/{postId}": { "get": { "summary": "Get a post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "postId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "media": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "count": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "kind", "count", "thumbnailUrl" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "sound": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ] }, "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": "Legacy earliest-release floor, returned only when an existing queue item already has one." }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "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": "Legacy earliest-release floor, returned only when an existing queue item already has one." }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } }, "delete": { "summary": "Cancel a post", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "postId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": false, "name": "accountId", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "media": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "image" ] }, "count": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "kind", "count", "thumbnailUrl" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "sound": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "trending", "original", "specific" ] }, "url": { "type": "string", "format": "uri" }, "urlsByPlatform": { "type": "object", "properties": { "tiktok": { "type": "string", "format": "uri" }, "instagram": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "mode" ], "additionalProperties": false }, "notes": { "type": [ "string", "null" ] }, "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": "Legacy earliest-release floor, returned only when an existing queue item already has one." }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts/{accountId}/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" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } }, "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" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts": { "get": { "summary": "List publishing accounts", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "required": false, "name": "platform", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "username": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "timezone": { "type": "string" }, "followers": { "type": "number" }, "postsToday": { "type": "integer" }, "dailyCap": { "type": "integer" }, "queueDepth": { "type": "integer" }, "nextWindow": { "type": [ "string", "null" ], "format": "date-time" }, "lastPostAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "accountId", "platform", "username", "displayName", "status", "timezone", "followers", "postsToday", "dailyCap", "queueDepth", "nextWindow", "lastPostAt" ] } } }, "required": [ "data" ] } } } } } }, "post": { "summary": "Create a publishing account", "security": [ { "bearerAuth": [] } ], "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.", "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" }, "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": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "username": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "timezone": { "type": "string" }, "followers": { "type": "number" }, "postsToday": { "type": "integer" }, "dailyCap": { "type": "integer" }, "queueDepth": { "type": "integer" }, "nextWindow": { "type": [ "string", "null" ], "format": "date-time" }, "lastPostAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "accountId", "platform", "username", "displayName", "status", "timezone", "followers", "postsToday", "dailyCap", "queueDepth", "nextWindow", "lastPostAt" ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts/{accountId}": { "get": { "summary": "Get a publishing account", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "accountId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "instagram" ] }, "username": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "timezone": { "type": "string" }, "followers": { "type": "number" }, "postsToday": { "type": "integer" }, "dailyCap": { "type": "integer" }, "queueDepth": { "type": "integer" }, "nextWindow": { "type": [ "string", "null" ], "format": "date-time" }, "lastPostAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "accountId", "platform", "username", "displayName", "status", "timezone", "followers", "postsToday", "dailyCap", "queueDepth", "nextWindow", "lastPostAt" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/accounts/{accountId}/queue": { "get": { "summary": "Get an account queue", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "accountId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "postId": { "type": "string" }, "queueItemId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "queued", "posting", "posted", "partially_posted", "cancelled", "processing", "failed" ] }, "caption": { "type": "string" }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" }, "queuedAt": { "type": "string", "format": "date-time" }, "scheduledAfter": { "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" } }, "required": [ "accountId", "followers", "posts", "engagement", "analytics", "scannedPosts" ] } } } } } } }, "/v2/usage": { "get": { "summary": "Get plan and API usage", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": [ "string", "null" ] }, "billingType": { "type": [ "string", "null" ] }, "videoQuota": { "type": [ "number", "null" ] }, "videoCount": { "type": [ "number", "null" ] }, "postCredits": { "type": [ "object", "null" ], "properties": { "limit": { "type": "number" }, "used": { "type": "number" } }, "required": [ "limit", "used" ] }, "postsPerDay": { "type": "number" }, "apiRequestsToday": { "type": "number" }, "postsCreatedToday": { "type": "number" } }, "required": [ "plan", "billingType", "videoQuota", "videoCount", "postCredits", "postsPerDay", "apiRequestsToday", "postsCreatedToday" ] } } } } } } }, "/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" ] }, "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 }, "warmupSearchTerms": { "type": "array", "items": { "type": "string", "maxLength": 80 } } }, "required": [ "accountId", "platform", "username", "displayName", "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" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } }, "/v2/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" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } } } } } } } }, "webhooks": {} }