{ "openapi": "3.0.3", "info": { "title": "Repostly API", "version": "1.0.0", "description": "Schedule posts to your connected social accounts, upload media, manage repost workflows and read analytics.\n\nAuthenticate with `Authorization: Bearer rp_live_…` (create keys in the Repostly app under Account → API keys). Paid plans only: without a plan every operation except GET /me returns 403 PLAN_REQUIRED.\n\nLists return `{ data, nextCursor }`; pass nextCursor as `cursor` (limit 1–100, default 20). Times accept ISO 8601 with offset or Unix milliseconds and are returned as ISO 8601 UTC. Errors are `{ error: { code, message, requestId, details } }`; validation errors list `details.fields`.\n\nRate limits are per account per UTC minute across all keys (see x-rate-limits). Connecting accounts, billing and key management happen in the app." }, "servers": [ { "url": "https://api.repostly.app/v1" } ], "tags": [ { "name": "Account", "description": "The API key owner." }, { "name": "Accounts", "description": "Connected social accounts." }, { "name": "Assets", "description": "Uploaded videos and images." }, { "name": "Posts", "description": "Scheduled, published and imported posts." }, { "name": "Workflows", "description": "Automatic reposting between accounts." }, { "name": "Analytics", "description": "Stored engagement observations." } ], "components": { "schemas": { "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 100 }, "message": { "type": "string", "maxLength": 1000 }, "requestId": { "type": "string", "maxLength": 100 }, "details": { "type": "object", "additionalProperties": true, "properties": { "fields": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "maxLength": 200 }, "message": { "type": "string", "maxLength": 500 } }, "required": ["field", "message"] } } } } }, "required": ["code", "message", "requestId"] } }, "required": ["error"] }, "Account": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "instagram", "facebook", "tiktok", "youtube", "threads", "twitter", "snapchat" ] }, "name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": ["active", "halted", "inactive"], "description": "halted: reconnect the account in the Repostly app." }, "followers": { "type": "number", "nullable": true }, "pages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": ["id", "name"] } }, "lastSyncedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last completed content synchronization." } }, "required": [ "id", "platform", "name", "status", "followers", "pages", "lastSyncedAt" ], "description": "A social account connected in the Repostly app." }, "Asset": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": ["video", "image"] }, "sizeBytes": { "type": "integer" }, "contentType": { "type": "string" }, "url": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "width": { "type": "integer" }, "height": { "type": "integer" }, "durationSeconds": { "type": "number" } }, "required": [ "id", "kind", "sizeBytes", "contentType", "url", "createdAt" ], "description": "An uploaded original. width/height/durationSeconds are present when inspection metadata exists." }, "UploadSession": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": ["video", "image"] }, "status": { "type": "string", "enum": [ "awaiting_upload", "processing", "ready", "failed", "expired", "cancelled" ], "description": "awaiting_upload → (complete) → processing → ready | failed. expired: not completed in time. cancelled: DELETE /uploads/{id}." }, "sizeBytes": { "type": "integer" }, "contentType": { "type": "string" }, "fileName": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the upload URL expires." }, "assetId": { "type": "string", "nullable": true, "description": "The library asset (use as videoAssetId, thumbnailAssetId or in imageAssetIds) once ready." }, "asset": { "anyOf": [ { "$ref": "#/components/schemas/Asset" }, { "type": "object", "nullable": true, "enum": [null] } ], "description": "The ready library asset; null until status is ready." }, "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "nullable": true, "description": "Why the upload failed, expired or was cancelled." } }, "required": [ "id", "kind", "status", "sizeBytes", "contentType", "fileName", "createdAt", "expiresAt", "assetId", "asset", "error" ], "description": "A direct upload: PUT the file to the upload URL, complete it, then poll until ready." }, "DestinationOptions": { "type": "object", "additionalProperties": false, "properties": { "caption": { "type": "string", "maxLength": 4000, "description": "Caption for this destination only (overrides the post caption)." }, "title": { "type": "string", "maxLength": 200, "description": "YouTube: the video title, at most 100 characters without < or > (YouTube uses the caption as title). Facebook video: the video title (at most 200)." }, "description": { "type": "string", "maxLength": 5000, "description": "YouTube and Facebook video description." }, "visibility": { "type": "string", "enum": ["public", "unlisted", "private"], "description": "YouTube video visibility. Default public." }, "tags": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 100 }, "description": "YouTube tags." }, "categoryId": { "type": "string", "maxLength": 3, "description": "YouTube category ID." }, "selfDeclaredMadeForKids": { "type": "boolean", "description": "YouTube: made for kids." }, "containsSyntheticMedia": { "type": "boolean", "description": "YouTube: altered or synthetic content disclosure." }, "notifySubscribers": { "type": "boolean", "description": "YouTube: notify subscribers." }, "shareToFeed": { "type": "boolean", "description": "Instagram Reels: also share to the feed." }, "thumbOffsetMs": { "type": "integer", "minimum": 0, "maximum": 86400000, "description": "Instagram Reels: cover frame offset in milliseconds." }, "altText": { "type": "string", "maxLength": 1000, "description": "Image alt text (Instagram, Facebook, Threads)." }, "aiGenerated": { "type": "boolean", "description": "Instagram / Facebook Reels: AI-generated label." }, "replyControl": { "type": "string", "enum": [ "everyone", "accounts_you_follow", "mentioned_only", "parent_post_author_only", "followers_only" ], "description": "Threads reply control." }, "topicTag": { "type": "string", "maxLength": 50, "description": "Threads topic tag." }, "tiktokPrivacyLevel": { "type": "string", "enum": [ "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY" ], "description": "TikTok privacy level; must be one of privacyLevelOptions from tiktok-creator-info." }, "allowComments": { "type": "boolean", "description": "TikTok: allow comments (explicit choice required)." }, "allowDuet": { "type": "boolean", "description": "TikTok video: allow duets (explicit choice required)." }, "allowStitch": { "type": "boolean", "description": "TikTok video: allow stitches (explicit choice required)." }, "commercialContent": { "type": "boolean", "description": "TikTok: commercial content disclosure; true exactly when brandedContent or promoteBrand is true." }, "brandedContent": { "type": "boolean", "description": "TikTok: branded content (paid partnership)." }, "promoteBrand": { "type": "boolean", "description": "TikTok: promotes your own brand." }, "aiContent": { "type": "boolean", "description": "TikTok: AI-generated content label." }, "tiktokPhotoTitle": { "type": "string", "maxLength": 90, "description": "TikTok photo posts: title (required for photo posts)." }, "tiktokAutoAddMusic": { "type": "boolean", "description": "TikTok photo posts: let TikTok add music (required for photo posts)." } }, "required": [], "description": "Stored editable settings for this destination, in the same form PUT /posts/{id} accepts. Present on GET /posts/{id} for editable posts. TikTok consent is never returned: send the creator's fresh tiktokConsent with every PUT." }, "Destination": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": ":" }, "accountId": { "type": "string" }, "accountName": { "type": "string", "nullable": true }, "platform": { "type": "string" }, "placement": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "scheduled", "queued", "processing", "published", "failed", "unknown", "cancelled", "paused" ], "description": "unknown: the platform outcome is uncertain; check the account before publishing again. paused: waiting on the account or plan, or past its time (see /posts/late)." }, "url": { "type": "string", "nullable": true, "description": "Public URL once published." }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true }, "providerPostIds": { "type": "array", "items": { "type": "string" } }, "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "nullable": true }, "metrics": { "type": "object", "additionalProperties": false, "properties": { "views": { "type": "number", "nullable": true }, "likes": { "type": "number", "nullable": true }, "comments": { "type": "number", "nullable": true }, "observedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": ["views", "likes", "comments", "observedAt"], "nullable": true }, "options": { "$ref": "#/components/schemas/DestinationOptions" } }, "required": [ "id", "accountId", "accountName", "platform", "placement", "status", "url", "publishedAt", "providerPostIds", "error", "metrics" ] }, "Post": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": ["video", "image", "carousel", "text"] }, "caption": { "type": "string" }, "status": { "type": "string", "enum": [ "scheduled", "publishing", "published", "partially_published", "failed", "paused", "cancelled" ], "description": "Aggregate of destination statuses: published (all), partially_published (some published, rest failed), failed (all), publishing (any queued/processing/unknown, or some finished while others wait), paused (any paused), cancelled (all cancelled), otherwise scheduled." }, "scheduledAt": { "type": "string", "format": "date-time", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "origin": { "type": "string", "enum": ["schedule", "workflow", "imported"] }, "workflowId": { "type": "string", "nullable": true }, "videoAssetId": { "type": "string", "nullable": true }, "thumbnailAssetId": { "type": "string", "nullable": true }, "imageAssetIds": { "type": "array", "items": { "type": "string" } }, "thumbnailUrl": { "type": "string", "nullable": true }, "editable": { "type": "boolean", "description": "true while PUT/DELETE can still change the post." }, "destinations": { "type": "array", "items": { "$ref": "#/components/schemas/Destination" } } }, "required": [ "id", "kind", "caption", "status", "scheduledAt", "timezone", "origin", "workflowId", "videoAssetId", "thumbnailAssetId", "imageAssetIds", "thumbnailUrl", "editable", "destinations" ], "description": "One piece of content published to one or more destinations. The ID is stable across destinations and edits." }, "WorkflowSide": { "type": "object", "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "accountName": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true }, "pageId": { "type": "string", "nullable": true } }, "required": [ "accountId", "accountName", "platform", "content", "pageId" ] }, "Workflow": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": ["active", "paused"] }, "mode": { "type": "string", "enum": ["new_posts", "backlog"] }, "source": { "$ref": "#/components/schemas/WorkflowSide" }, "destination": { "$ref": "#/components/schemas/WorkflowSide" }, "backlog": { "type": "object", "additionalProperties": false, "properties": { "startAt": { "type": "string", "format": "date-time", "nullable": true }, "timezone": { "type": "string" }, "order": { "type": "string", "enum": ["oldest_first", "from_date"] }, "postTimes": { "type": "array", "items": { "type": "string" } } }, "required": ["startAt", "timezone", "order", "postTimes"], "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "name", "status", "mode", "source", "destination", "backlog", "createdAt" ] }, "ProcessingItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": ["pending", "preparing", "blocked", "handed_off"] }, "blockedReason": { "type": "string", "nullable": true }, "postId": { "type": "string", "nullable": true, "description": "The resulting post once handed off." }, "sourceCaption": { "type": "string", "nullable": true }, "sourcePostedAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "state", "blockedReason", "postId", "sourceCaption", "sourcePostedAt", "updatedAt" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Repostly API key (rp_live_…)" } } }, "x-rate-limits": { "windowSeconds": 60, "starter": { "total": 120, "writes": 30, "uploads": 6, "analytics": 30, "creatorInfo": 6 }, "pro": { "total": 300, "writes": 60, "uploads": 12, "analytics": 60, "creatorInfo": 6 }, "expert": { "total": 600, "writes": 120, "uploads": 20, "analytics": 120, "creatorInfo": 6 }, "none": { "total": 60, "writes": 0, "uploads": 0, "analytics": 0, "creatorInfo": 0 } }, "paths": { "/me": { "get": { "operationId": "getMe", "summary": "Get the API key owner", "description": "Your Repostly plan, this key's scopes and expiry, your per-minute rate limits and useful app links. Works with any scope and without a paid plan (plan is \"none\" then; every other operation returns 403 PLAN_REQUIRED — upgrade at https://app.repostly.app/upgrade).\n\nScope: any. Rate bucket: total only.", "tags": ["Account"], "security": [ { "bearerAuth": [] } ], "x-scope": null, "x-rate-limit-bucket": "total", "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "userId": { "type": "string" }, "plan": { "type": "string", "enum": ["starter", "pro", "expert", "none"] }, "key": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": ["id", "name", "scopes", "expiresAt"] }, "rateLimits": { "type": "object", "additionalProperties": false, "properties": { "windowSeconds": { "type": "integer" }, "total": { "type": "integer" }, "writes": { "type": "integer" }, "uploads": { "type": "integer" }, "analytics": { "type": "integer" }, "creatorInfo": { "type": "integer" } }, "required": [ "windowSeconds", "total", "writes", "uploads", "analytics", "creatorInfo" ] }, "links": { "type": "object", "additionalProperties": false, "properties": { "app": { "type": "string" }, "connectAccounts": { "type": "string" }, "upgrade": { "type": "string" }, "docs": { "type": "string" } }, "required": ["app", "connectAccounts", "upgrade", "docs"] } }, "required": ["userId", "plan", "key", "rateLimits", "links"] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts": { "get": { "operationId": "listAccounts", "summary": "List connected accounts", "description": "Social accounts connected in the Repostly app (connect or reconnect them at links.connectAccounts from GET /me). Provider credentials are never returned.\n\nScope: accounts:read. Rate bucket: total only.", "tags": ["Accounts"], "security": [ { "bearerAuth": [] } ], "x-scope": "accounts:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "platform", "in": "query", "required": false, "description": "Only accounts on this platform.", "schema": { "type": "string", "enum": ["instagram", "facebook", "tiktok", "youtube", "threads"] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–100, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque nextCursor from the previous page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as cursor to get the next page; null on the last page." } }, "required": ["data", "nextCursor"] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/{id}": { "get": { "operationId": "getAccount", "summary": "Get a connected account", "description": "One connected account. pages lists selectable pages when the connection has them; otherwise it is empty.\n\nScope: accounts:read. Rate bucket: total only.", "tags": ["Accounts"], "security": [ { "bearerAuth": [] } ], "x-scope": "accounts:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/{id}/tiktok-creator-info": { "get": { "operationId": "getTiktokCreatorInfo", "summary": "Get TikTok creator publishing options", "description": "Live TikTok creator capabilities: nickname, allowed privacy levels, whether comments/duets/stitches are available and the maximum video duration. TikTok requires showing these choices and collecting explicit consent before posting; use them to fill the TikTok destination fields of POST /posts. Only for TikTok accounts.\n\nScope: accounts:read. Rate bucket: creatorInfo.", "tags": ["Accounts"], "security": [ { "bearerAuth": [] } ], "x-scope": "accounts:read", "x-rate-limit-bucket": "creatorInfo", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "creatorNickname": { "type": "string", "nullable": true }, "creatorUsername": { "type": "string", "nullable": true }, "creatorAvatarUrl": { "type": "string", "nullable": true }, "privacyLevelOptions": { "type": "array", "items": { "type": "string" } }, "commentDisabled": { "type": "boolean" }, "duetDisabled": { "type": "boolean" }, "stitchDisabled": { "type": "boolean" }, "maxVideoPostDurationSec": { "type": "number", "nullable": true }, "checkedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "creatorNickname", "creatorUsername", "creatorAvatarUrl", "privacyLevelOptions", "commentDisabled", "duetDisabled", "stitchDisabled", "maxVideoPostDurationSec", "checkedAt" ] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Content or destination not supported, or required consent missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets": { "get": { "operationId": "listAssets", "summary": "List uploaded assets", "description": "Your uploaded originals, newest first.\n\nScope: assets:read. Rate bucket: total only.", "tags": ["Assets"], "security": [ { "bearerAuth": [] } ], "x-scope": "assets:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Only this kind.", "schema": { "type": "string", "enum": ["video", "image"] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–100, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque nextCursor from the previous page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as cursor to get the next page; null on the last page." } }, "required": ["data", "nextCursor"] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "uploadAsset", "summary": "Upload a video or image", "description": "multipart/form-data with exactly one file part named file (mediaFile is accepted too). The kind is inferred from the file (JPEG/PNG → image, MP4/MOV → video); ?kind= overrides it. Limits: video 100 MiB, image 20 MiB, one upload at a time per account. Uploading the same file again returns the same asset. Remote URLs are not fetched: upload the bytes.\n\nScope: assets:write. Rate bucket: uploads.", "tags": ["Assets"], "security": [ { "bearerAuth": [] } ], "x-scope": "assets:write", "x-rate-limit-bucket": "uploads", "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Override the inferred kind.", "schema": { "type": "string", "enum": ["video", "image"] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary", "description": "The video or image (alias: mediaFile)." } } } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Upload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Content or destination not supported, or required consent missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/assets/{id}": { "get": { "operationId": "getAsset", "summary": "Get an asset", "description": "One uploaded original.\n\nScope: assets:read. Rate bucket: total only.", "tags": ["Assets"], "security": [ { "bearerAuth": [] } ], "x-scope": "assets:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/uploads": { "post": { "operationId": "createUpload", "summary": "Start a direct upload", "description": "Recommended for videos (up to 500 MiB; images up to 20 MiB). Returns a one-hour presigned upload URL: PUT the file bytes there with exactly upload.headers (no Authorization header), then call POST /uploads/{id}/complete and poll GET /uploads/{id} until status is ready; asset.id is then usable as videoAssetId, thumbnailAssetId or in imageAssetIds. At most 3 uploads may be awaiting upload or processing per account (409 TOO_MANY_UPLOADS; uploads whose file never arrived are cancelled automatically once old enough, or cancel them with DELETE /uploads/{id}), and 10 GiB may be declared per rolling 24 hours (429 UPLOAD_QUOTA_EXCEEDED). 503 DIRECT_UPLOAD_UNAVAILABLE: use multipart POST /assets instead. Requires an Idempotency-Key: retry with the same key and body after a timeout; the original result is replayed (Idempotency-Replayed: true, with its Retry-After). Keys are remembered for 30 days. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: assets:write. Rate bucket: uploads.", "tags": ["Assets"], "security": [ { "bearerAuth": [] } ], "x-scope": "assets:write", "x-rate-limit-bucket": "uploads", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Unique per logical action. Retry with the same key and body after a timeout; remembered for 30 days." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": ["video", "image"], "description": "Optional; inferred from contentType and must match it." }, "contentType": { "type": "string", "enum": [ "video/mp4", "video/quicktime", "image/jpeg", "image/png" ], "description": "The file's MIME type. Signed into the upload URL." }, "sizeBytes": { "type": "integer", "minimum": 1, "description": "Exact file size in bytes (video ≤ 524288000 = 500 MiB, image ≤ 20971520 = 20 MiB). Signed into the upload URL." }, "fileName": { "type": "string", "maxLength": 255, "description": "Display name only (stored up to 200 characters)." } }, "required": ["contentType", "sizeBytes"] }, "example": { "kind": "video", "contentType": "video/mp4", "sizeBytes": 471859200, "fileName": "launch.mp4" } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": ["video", "image"] }, "status": { "type": "string", "enum": ["awaiting_upload"] }, "sizeBytes": { "type": "integer" }, "contentType": { "type": "string" }, "fileName": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "assetId": { "type": "string", "nullable": true }, "asset": { "anyOf": [ { "$ref": "#/components/schemas/Asset" }, { "type": "object", "nullable": true, "enum": [null] } ] }, "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "nullable": true }, "upload": { "type": "object", "additionalProperties": false, "properties": { "method": { "type": "string", "enum": ["PUT"] }, "url": { "type": "string", "description": "Presigned storage URL. Send no Authorization header." }, "headers": { "type": "object", "additionalProperties": false, "properties": { "Content-Type": { "type": "string" }, "Content-Length": { "type": "string" } }, "required": ["Content-Type", "Content-Length"], "description": "Send exactly these headers; both are signed." }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["method", "url", "headers", "expiresAt"], "description": "Where to PUT the file bytes (valid for one hour)." }, "maxBytes": { "type": "integer" } }, "required": [ "id", "kind", "status", "sizeBytes", "contentType", "fileName", "createdAt", "expiresAt", "assetId", "asset", "error", "upload", "maxBytes" ], "description": "The new upload session and its one-hour upload URL." } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Upload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/uploads/{id}": { "get": { "operationId": "getUpload", "summary": "Get a direct upload", "description": "The upload's status. Poll every few seconds while processing (verification of a 500 MiB video usually takes well under a minute); ready includes the asset, failed includes error.code and a message. Polling also resumes verification interrupted by a server restart.\n\nScope: assets:read. Rate bucket: total only.", "tags": ["Assets"], "security": [ { "bearerAuth": [] } ], "x-scope": "assets:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "cancelUpload", "summary": "Cancel a direct upload", "description": "Cancels an upload that was not completed (status cancelled) so it stops counting toward the 3 concurrent uploads. Finished uploads are returned unchanged; 409 UPLOAD_PROCESSING once complete was called. Never deletes a ready asset. An Idempotency-Key is optional and honored when sent. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: assets:write. Rate bucket: total only.", "tags": ["Assets"], "security": [ { "bearerAuth": [] } ], "x-scope": "assets:write", "x-rate-limit-bucket": "total", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Optional. When sent, retries with the same key and input replay the first result." } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/uploads/{id}/complete": { "post": { "operationId": "completeUpload", "summary": "Complete a direct upload", "description": "Call after the PUT succeeded. Starts verification (202, status processing): the size must equal sizeBytes and the content must be an MP4/MOV video or a JPEG/PNG image. Identical bytes already in your library return that asset. 409 UPLOAD_NOT_RECEIVED: the file is not in storage yet; retry the PUT if it failed, then complete again (the URL works until expiresAt). Send no body or {}. An Idempotency-Key is optional and honored when sent. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: assets:write. Rate bucket: total only.", "tags": ["Assets"], "security": [ { "bearerAuth": [] } ], "x-scope": "assets:write", "x-rate-limit-bucket": "total", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Optional. When sent, retries with the same key and input replay the first result." } ], "responses": { "200": { "description": "Already finished (ready, failed, expired or cancelled): returned unchanged, never re-run.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "202": { "description": "Accepted; processing.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts": { "get": { "operationId": "listPosts", "summary": "List posts", "description": "Posts created in Repostly (scheduled in the app or via the API, or by workflows) and posts imported from your connected accounts, newest scheduledAt first, with per-destination status.\n\nScope: posts:read. Rate bucket: total only.", "tags": ["Posts"], "security": [ { "bearerAuth": [] } ], "x-scope": "posts:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "accountId", "in": "query", "required": false, "description": "Only posts with a destination on this account.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "kind", "in": "query", "required": false, "description": "Only this content kind.", "schema": { "type": "string", "enum": ["video", "image", "carousel", "text"] } }, { "name": "from", "in": "query", "required": false, "description": "Only posts scheduled at or after this time. ISO 8601 date-time with offset (e.g. 2026-11-01T09:00:00Z) or Unix milliseconds.", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "maxLength": 40 }, { "type": "integer", "minimum": 0, "maximum": 253402300799999 } ] } }, { "name": "to", "in": "query", "required": false, "description": "Only posts scheduled before this time. ISO 8601 date-time with offset (e.g. 2026-11-01T09:00:00Z) or Unix milliseconds.", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "maxLength": 40 }, { "type": "integer", "minimum": 0, "maximum": 253402300799999 } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–100, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque nextCursor from the previous page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as cursor to get the next page; null on the last page." } }, "required": ["data", "nextCursor"] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createPost", "summary": "Create (schedule) a post", "description": "Schedules one piece of content to one or more connected accounts. The kind is inferred: videoAssetId → video, one image → image, 2–20 images → carousel, neither → text. Omit scheduledAt to publish on the next scheduler run. Audio a destination cannot accept is converted automatically before publishing. Publishing is asynchronous: watch each destination's status. Requires an Idempotency-Key: retry with the same key and body after a timeout; the original result is replayed (Idempotency-Replayed: true, with its Retry-After). Keys are remembered for 30 days. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: posts:write. Rate bucket: writes.", "tags": ["Posts"], "security": [ { "bearerAuth": [] } ], "x-scope": "posts:write", "x-rate-limit-bucket": "writes", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Unique per logical action. Retry with the same key and body after a timeout; remembered for 30 days." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "caption": { "type": "string", "maxLength": 4000, "description": "Shared caption. Required for text posts." }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time", "maxLength": 40 }, { "type": "integer", "minimum": 0, "maximum": 253402300799999 } ], "description": "When to publish. On create, omit it (or send a time up to 60 s in the past) to publish on the next scheduler run. On replace (PUT), omit it to keep the post's current scheduled time. ISO 8601 date-time with offset (e.g. 2026-11-01T09:00:00Z) or Unix milliseconds." }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "IANA time zone for display and email context (default UTC). It never reinterprets scheduledAt." }, "videoAssetId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Uploaded video asset (makes this a video post)." }, "thumbnailAssetId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Optional uploaded image asset used as the video thumbnail." }, "imageAssetIds": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "24-character hexadecimal ID." }, "description": "Uploaded image assets: one → image post, 2–20 → carousel." }, "destinations": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "properties": { "accountId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Connected account ID from GET /accounts." }, "placement": { "type": "string", "enum": [ "video", "shorts", "reels", "image", "carousel", "text" ], "description": "Where the content appears. Defaults: video posts → youtube video, instagram reels, facebook video, threads video, tiktok video; image → image; carousel → carousel; text → text." }, "caption": { "type": "string", "maxLength": 4000, "description": "Caption for this destination only (overrides the post caption)." }, "title": { "type": "string", "maxLength": 200, "description": "YouTube: the video title, at most 100 characters without < or > (YouTube uses the caption as title). Facebook video: the video title (at most 200)." }, "description": { "type": "string", "maxLength": 5000, "description": "YouTube and Facebook video description." }, "visibility": { "type": "string", "enum": ["public", "unlisted", "private"], "description": "YouTube video visibility. Default public." }, "tags": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 100 }, "description": "YouTube tags." }, "categoryId": { "type": "string", "maxLength": 3, "description": "YouTube category ID." }, "selfDeclaredMadeForKids": { "type": "boolean", "description": "YouTube: made for kids." }, "containsSyntheticMedia": { "type": "boolean", "description": "YouTube: altered or synthetic content disclosure." }, "notifySubscribers": { "type": "boolean", "description": "YouTube: notify subscribers." }, "shareToFeed": { "type": "boolean", "description": "Instagram Reels: also share to the feed." }, "thumbOffsetMs": { "type": "integer", "minimum": 0, "maximum": 86400000, "description": "Instagram Reels: cover frame offset in milliseconds." }, "altText": { "type": "string", "maxLength": 1000, "description": "Image alt text (Instagram, Facebook, Threads)." }, "aiGenerated": { "type": "boolean", "description": "Instagram / Facebook Reels: AI-generated label." }, "replyControl": { "type": "string", "enum": [ "everyone", "accounts_you_follow", "mentioned_only", "parent_post_author_only", "followers_only" ], "description": "Threads reply control." }, "topicTag": { "type": "string", "maxLength": 50, "description": "Threads topic tag." }, "tiktokPrivacyLevel": { "type": "string", "enum": [ "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY" ], "description": "TikTok privacy level; must be one of privacyLevelOptions from tiktok-creator-info." }, "allowComments": { "type": "boolean", "description": "TikTok: allow comments (explicit choice required)." }, "allowDuet": { "type": "boolean", "description": "TikTok video: allow duets (explicit choice required)." }, "allowStitch": { "type": "boolean", "description": "TikTok video: allow stitches (explicit choice required)." }, "commercialContent": { "type": "boolean", "description": "TikTok: commercial content disclosure; true exactly when brandedContent or promoteBrand is true." }, "brandedContent": { "type": "boolean", "description": "TikTok: branded content (paid partnership)." }, "promoteBrand": { "type": "boolean", "description": "TikTok: promotes your own brand." }, "aiContent": { "type": "boolean", "description": "TikTok: AI-generated content label." }, "tiktokPhotoTitle": { "type": "string", "maxLength": 90, "description": "TikTok photo posts: title (required for photo posts)." }, "tiktokAutoAddMusic": { "type": "boolean", "description": "TikTok photo posts: let TikTok add music (required for photo posts)." }, "tiktokConsent": { "type": "object", "additionalProperties": false, "properties": { "contentSharingConfirmed": { "type": "boolean", "description": "The creator confirmed TikTok's content sharing terms." }, "musicUsageConfirmed": { "type": "boolean", "description": "The creator confirmed TikTok's music usage confirmation." }, "brandedContentPolicyConfirmed": { "type": "boolean", "description": "Required when brandedContent is true." } }, "required": [ "contentSharingConfirmed", "musicUsageConfirmed" ], "description": "Explicit TikTok creator consent collected in your UI for this post. Required for TikTok destinations on every create and every replace (PUT); GET never returns stored consent." } }, "required": ["accountId"], "description": "One destination account and its platform options. Options that the account's platform does not use are rejected." } } }, "required": ["destinations"] }, "example": { "caption": "Launch day!", "scheduledAt": "2026-11-01T09:00:00+01:00", "timezone": "Europe/Berlin", "videoAssetId": "64b7f0c2a1e4d3b2c1f0e9d8", "destinations": [ { "accountId": "507f1f77bcf86cd799439011", "placement": "reels", "caption": "IG-specific caption", "shareToFeed": true }, { "accountId": "507f1f77bcf86cd799439012", "placement": "shorts", "title": "Launch day", "visibility": "public", "tags": ["launch"] }, { "accountId": "507f1f77bcf86cd799439013", "tiktokPrivacyLevel": "PUBLIC_TO_EVERYONE", "allowComments": true, "allowDuet": false, "allowStitch": false, "commercialContent": false, "brandedContent": false, "promoteBrand": false, "aiContent": false, "tiktokConsent": { "contentSharingConfirmed": true, "musicUsageConfirmed": true } } ] } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Content or destination not supported, or required consent missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/late": { "get": { "operationId": "listLatePosts", "summary": "List late posts", "description": "Posts paused past their scheduled time (for example after a plan lapse or a disconnected account). Resolve them with POST /posts/late/resolve.\n\nScope: posts:read. Rate bucket: total only.", "tags": ["Posts"], "security": [ { "bearerAuth": [] } ], "x-scope": "posts:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–100, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque nextCursor from the previous page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as cursor to get the next page; null on the last page." } }, "required": ["data", "nextCursor"] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/late/resolve": { "post": { "operationId": "resolveLatePosts", "summary": "Publish, reschedule or discard late posts", "description": "Resolves up to 100 late posts at once. publish queues them now; reschedule spaces them from startAt by spacingMinutes; discard cancels them. Each post is reported as resolved or skipped (with a reason). Requires an Idempotency-Key: retry with the same key and body after a timeout; the original result is replayed (Idempotency-Replayed: true, with its Retry-After). Keys are remembered for 30 days. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: posts:write. Rate bucket: writes.", "tags": ["Posts"], "security": [ { "bearerAuth": [] } ], "x-scope": "posts:write", "x-rate-limit-bucket": "writes", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Unique per logical action. Retry with the same key and body after a timeout; remembered for 30 days." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "action": { "type": "string", "enum": ["publish", "reschedule", "discard"], "description": "publish now, reschedule from startAt, or discard (cancel)." }, "postIds": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "24-character hexadecimal ID." } }, "startAt": { "anyOf": [ { "type": "string", "format": "date-time", "maxLength": 40 }, { "type": "integer", "minimum": 0, "maximum": 253402300799999 } ], "description": "reschedule: the first new publishing time (must not be in the past). ISO 8601 date-time with offset (e.g. 2026-11-01T09:00:00Z) or Unix milliseconds." }, "spacingMinutes": { "type": "integer", "minimum": 0, "maximum": 240, "default": 15, "description": "reschedule: minutes between consecutive posts." } }, "required": ["action", "postIds"] }, "example": { "action": "reschedule", "postIds": ["507f1f77bcf86cd799439011"], "startAt": "2026-11-02T09:00:00Z", "spacingMinutes": 30 } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "resolved": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "postId": { "type": "string" }, "scheduledAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": ["postId", "scheduledAt"] } }, "skipped": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "postId": { "type": "string" }, "reason": { "type": "string" } }, "required": ["postId", "reason"] } } }, "required": ["resolved", "skipped"] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/{id}": { "get": { "operationId": "getPost", "summary": "Get a post", "description": "One post and its destinations. For editable posts each destination includes options in the form PUT /posts/{id} accepts, so you can GET, modify and PUT.\n\nScope: posts:read. Rate bucket: total only.", "tags": ["Posts"], "security": [ { "bearerAuth": [] } ], "x-scope": "posts:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Post ID. Posts imported from a connected account use the form imported:.", "schema": { "type": "string", "pattern": "^(imported:)?[a-fA-F0-9]{24}$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "replacePost", "summary": "Replace a scheduled post", "description": "Full replacement (same body as create) of a post that has not started publishing; omitting scheduledAt keeps the post's current scheduled time. Returns 409 once publishing started and for workflow posts (409 POST_BUSY while the scheduler or another change holds the post: retry shortly). The content kind cannot change. Keeping the same videoAssetId keeps its prepared audio. An Idempotency-Key is optional and honored when sent. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: posts:write. Rate bucket: writes.", "tags": ["Posts"], "security": [ { "bearerAuth": [] } ], "x-scope": "posts:write", "x-rate-limit-bucket": "writes", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Optional. When sent, retries with the same key and input replay the first result." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "caption": { "type": "string", "maxLength": 4000, "description": "Shared caption. Required for text posts." }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time", "maxLength": 40 }, { "type": "integer", "minimum": 0, "maximum": 253402300799999 } ], "description": "When to publish. On create, omit it (or send a time up to 60 s in the past) to publish on the next scheduler run. On replace (PUT), omit it to keep the post's current scheduled time. ISO 8601 date-time with offset (e.g. 2026-11-01T09:00:00Z) or Unix milliseconds." }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "IANA time zone for display and email context (default UTC). It never reinterprets scheduledAt." }, "videoAssetId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Uploaded video asset (makes this a video post)." }, "thumbnailAssetId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Optional uploaded image asset used as the video thumbnail." }, "imageAssetIds": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "24-character hexadecimal ID." }, "description": "Uploaded image assets: one → image post, 2–20 → carousel." }, "destinations": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "properties": { "accountId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Connected account ID from GET /accounts." }, "placement": { "type": "string", "enum": [ "video", "shorts", "reels", "image", "carousel", "text" ], "description": "Where the content appears. Defaults: video posts → youtube video, instagram reels, facebook video, threads video, tiktok video; image → image; carousel → carousel; text → text." }, "caption": { "type": "string", "maxLength": 4000, "description": "Caption for this destination only (overrides the post caption)." }, "title": { "type": "string", "maxLength": 200, "description": "YouTube: the video title, at most 100 characters without < or > (YouTube uses the caption as title). Facebook video: the video title (at most 200)." }, "description": { "type": "string", "maxLength": 5000, "description": "YouTube and Facebook video description." }, "visibility": { "type": "string", "enum": ["public", "unlisted", "private"], "description": "YouTube video visibility. Default public." }, "tags": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 100 }, "description": "YouTube tags." }, "categoryId": { "type": "string", "maxLength": 3, "description": "YouTube category ID." }, "selfDeclaredMadeForKids": { "type": "boolean", "description": "YouTube: made for kids." }, "containsSyntheticMedia": { "type": "boolean", "description": "YouTube: altered or synthetic content disclosure." }, "notifySubscribers": { "type": "boolean", "description": "YouTube: notify subscribers." }, "shareToFeed": { "type": "boolean", "description": "Instagram Reels: also share to the feed." }, "thumbOffsetMs": { "type": "integer", "minimum": 0, "maximum": 86400000, "description": "Instagram Reels: cover frame offset in milliseconds." }, "altText": { "type": "string", "maxLength": 1000, "description": "Image alt text (Instagram, Facebook, Threads)." }, "aiGenerated": { "type": "boolean", "description": "Instagram / Facebook Reels: AI-generated label." }, "replyControl": { "type": "string", "enum": [ "everyone", "accounts_you_follow", "mentioned_only", "parent_post_author_only", "followers_only" ], "description": "Threads reply control." }, "topicTag": { "type": "string", "maxLength": 50, "description": "Threads topic tag." }, "tiktokPrivacyLevel": { "type": "string", "enum": [ "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY" ], "description": "TikTok privacy level; must be one of privacyLevelOptions from tiktok-creator-info." }, "allowComments": { "type": "boolean", "description": "TikTok: allow comments (explicit choice required)." }, "allowDuet": { "type": "boolean", "description": "TikTok video: allow duets (explicit choice required)." }, "allowStitch": { "type": "boolean", "description": "TikTok video: allow stitches (explicit choice required)." }, "commercialContent": { "type": "boolean", "description": "TikTok: commercial content disclosure; true exactly when brandedContent or promoteBrand is true." }, "brandedContent": { "type": "boolean", "description": "TikTok: branded content (paid partnership)." }, "promoteBrand": { "type": "boolean", "description": "TikTok: promotes your own brand." }, "aiContent": { "type": "boolean", "description": "TikTok: AI-generated content label." }, "tiktokPhotoTitle": { "type": "string", "maxLength": 90, "description": "TikTok photo posts: title (required for photo posts)." }, "tiktokAutoAddMusic": { "type": "boolean", "description": "TikTok photo posts: let TikTok add music (required for photo posts)." }, "tiktokConsent": { "type": "object", "additionalProperties": false, "properties": { "contentSharingConfirmed": { "type": "boolean", "description": "The creator confirmed TikTok's content sharing terms." }, "musicUsageConfirmed": { "type": "boolean", "description": "The creator confirmed TikTok's music usage confirmation." }, "brandedContentPolicyConfirmed": { "type": "boolean", "description": "Required when brandedContent is true." } }, "required": [ "contentSharingConfirmed", "musicUsageConfirmed" ], "description": "Explicit TikTok creator consent collected in your UI for this post. Required for TikTok destinations on every create and every replace (PUT); GET never returns stored consent." } }, "required": ["accountId"], "description": "One destination account and its platform options. Options that the account's platform does not use are rejected." } } }, "required": ["destinations"] }, "example": { "caption": "Launch day!", "scheduledAt": "2026-11-01T09:00:00+01:00", "timezone": "Europe/Berlin", "videoAssetId": "64b7f0c2a1e4d3b2c1f0e9d8", "destinations": [ { "accountId": "507f1f77bcf86cd799439011", "placement": "reels", "caption": "IG-specific caption", "shareToFeed": true }, { "accountId": "507f1f77bcf86cd799439012", "placement": "shorts", "title": "Launch day", "visibility": "public", "tags": ["launch"] } ] } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Content or destination not supported, or required consent missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "cancelPost", "summary": "Cancel a scheduled post", "description": "Cancels a post that has not started publishing (204). Never deletes content that is already live on a platform. An Idempotency-Key is optional and honored when sent. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: posts:write. Rate bucket: writes.", "tags": ["Posts"], "security": [ { "bearerAuth": [] } ], "x-scope": "posts:write", "x-rate-limit-bucket": "writes", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Optional. When sent, retries with the same key and input replay the first result." } ], "responses": { "204": { "description": "Done; no content.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/{id}/analytics": { "get": { "operationId": "getPostAnalytics", "summary": "Get post engagement over time", "description": "Net change in views, likes and comments per hour (24h) or day (7d, 30d), for the post and for each published destination. Values are null where no observation exists.\n\nScope: analytics:read. Rate bucket: analytics.", "tags": ["Posts"], "security": [ { "bearerAuth": [] } ], "x-scope": "analytics:read", "x-rate-limit-bucket": "analytics", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Post ID. Posts imported from a connected account use the form imported:.", "schema": { "type": "string", "pattern": "^(imported:)?[a-fA-F0-9]{24}$" } }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["24h", "7d", "30d"], "default": "7d" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "postId": { "type": "string" }, "range": { "type": "string" }, "timezone": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "at": { "type": "string", "format": "date-time" }, "views": { "type": "number", "nullable": true }, "likes": { "type": "number", "nullable": true }, "comments": { "type": "number", "nullable": true } }, "required": ["at", "views", "likes", "comments"] } }, "destinations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "platform": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "at": { "type": "string", "format": "date-time" }, "views": { "type": "number", "nullable": true }, "likes": { "type": "number", "nullable": true }, "comments": { "type": "number", "nullable": true } }, "required": ["at", "views", "likes", "comments"] } } }, "required": ["accountId", "platform", "points"] } } }, "required": [ "postId", "range", "timezone", "points", "destinations" ] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows": { "get": { "operationId": "listWorkflows", "summary": "List workflows", "description": "Workflows automatically repost content from a source account to a destination account.\n\nScope: workflows:read. Rate bucket: total only.", "tags": ["Workflows"], "security": [ { "bearerAuth": [] } ], "x-scope": "workflows:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–100, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque nextCursor from the previous page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as cursor to get the next page; null on the last page." } }, "required": ["data", "nextCursor"] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createWorkflow", "summary": "Create a workflow", "description": "Creates an active workflow. mode new_posts reposts content as it appears; backlog works through existing content at the daily postTimes. Source/destination combinations follow the app's supported matrix (422 otherwise); TikTok destinations need tiktokDeclaration: true; loops return 508. Requires an Idempotency-Key: retry with the same key and body after a timeout; the original result is replayed (Idempotency-Replayed: true, with its Retry-After). Keys are remembered for 30 days. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: workflows:write. Rate bucket: writes.", "tags": ["Workflows"], "security": [ { "bearerAuth": [] } ], "x-scope": "workflows:write", "x-rate-limit-bucket": "writes", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Unique per logical action. Retry with the same key and body after a timeout; remembered for 30 days." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "sourceAccountId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Account to repost from." }, "destinationAccountId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Account to publish to." }, "sourceContent": { "type": "string", "enum": [ "reels", "video", "videos", "shorts", "text", "image", "carousel" ], "description": "Source content type to repost." }, "destinationContent": { "type": "string", "enum": [ "reels", "video", "videos", "shorts", "text", "image", "carousel" ], "description": "Destination content type." }, "mode": { "type": "string", "enum": ["new_posts", "backlog"], "description": "new_posts: repost new content as it appears. backlog: work through existing content on a schedule." }, "backlog": { "type": "object", "additionalProperties": false, "properties": { "startAt": { "anyOf": [ { "type": "string", "format": "date-time", "maxLength": 40 }, { "type": "integer", "minimum": 0, "maximum": 253402300799999 } ], "description": "from_date order: the first source post date to repost from. Ignored for oldest_first. ISO 8601 date-time with offset (e.g. 2026-11-01T09:00:00Z) or Unix milliseconds." }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Time zone of postTimes (default UTC)." }, "order": { "type": "string", "enum": ["oldest_first", "from_date"], "description": "Default oldest_first." }, "postTimes": { "type": "array", "minItems": 1, "maxItems": 24, "uniqueItems": true, "items": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "description": "Daily publishing times, 24-hour HH:mm." } }, "required": ["postTimes"], "description": "Required when mode is backlog." }, "tiktokDeclaration": { "type": "boolean", "description": "Required for TikTok destinations: the user confirmed the workflow publishing declaration." } }, "required": [ "sourceAccountId", "destinationAccountId", "sourceContent", "destinationContent", "mode" ] }, "example": { "sourceAccountId": "507f1f77bcf86cd799439011", "destinationAccountId": "507f1f77bcf86cd799439012", "sourceContent": "reels", "destinationContent": "shorts", "mode": "backlog", "backlog": { "startAt": "2026-11-01T00:00:00Z", "timezone": "Europe/Berlin", "order": "from_date", "postTimes": ["09:00", "18:30"] } } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Content or destination not supported, or required consent missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "508": { "description": "The workflow would create a repost loop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{id}": { "get": { "operationId": "getWorkflow", "summary": "Get a workflow", "description": "One workflow's settings and status.\n\nScope: workflows:read. Rate bucket: total only.", "tags": ["Workflows"], "security": [ { "bearerAuth": [] } ], "x-scope": "workflows:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "replaceWorkflow", "summary": "Replace a workflow", "description": "Full replacement of a workflow's settings (same body as create). As in the app, saving reactivates a paused workflow. An Idempotency-Key is optional and honored when sent. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: workflows:write. Rate bucket: writes.", "tags": ["Workflows"], "security": [ { "bearerAuth": [] } ], "x-scope": "workflows:write", "x-rate-limit-bucket": "writes", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Optional. When sent, retries with the same key and input replay the first result." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "sourceAccountId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Account to repost from." }, "destinationAccountId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Account to publish to." }, "sourceContent": { "type": "string", "enum": [ "reels", "video", "videos", "shorts", "text", "image", "carousel" ], "description": "Source content type to repost." }, "destinationContent": { "type": "string", "enum": [ "reels", "video", "videos", "shorts", "text", "image", "carousel" ], "description": "Destination content type." }, "mode": { "type": "string", "enum": ["new_posts", "backlog"], "description": "new_posts: repost new content as it appears. backlog: work through existing content on a schedule." }, "backlog": { "type": "object", "additionalProperties": false, "properties": { "startAt": { "anyOf": [ { "type": "string", "format": "date-time", "maxLength": 40 }, { "type": "integer", "minimum": 0, "maximum": 253402300799999 } ], "description": "from_date order: the first source post date to repost from. Ignored for oldest_first. ISO 8601 date-time with offset (e.g. 2026-11-01T09:00:00Z) or Unix milliseconds." }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Time zone of postTimes (default UTC)." }, "order": { "type": "string", "enum": ["oldest_first", "from_date"], "description": "Default oldest_first." }, "postTimes": { "type": "array", "minItems": 1, "maxItems": 24, "uniqueItems": true, "items": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }, "description": "Daily publishing times, 24-hour HH:mm." } }, "required": ["postTimes"], "description": "Required when mode is backlog." }, "tiktokDeclaration": { "type": "boolean", "description": "Required for TikTok destinations: the user confirmed the workflow publishing declaration." } }, "required": [ "sourceAccountId", "destinationAccountId", "sourceContent", "destinationContent", "mode" ] }, "example": { "sourceAccountId": "507f1f77bcf86cd799439011", "destinationAccountId": "507f1f77bcf86cd799439012", "sourceContent": "reels", "destinationContent": "shorts", "mode": "new_posts" } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Content or destination not supported, or required consent missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "508": { "description": "The workflow would create a repost loop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteWorkflow", "summary": "Delete a workflow", "description": "Deletes the workflow (204). Posts it already created are kept. An Idempotency-Key is optional and honored when sent. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: workflows:write. Rate bucket: writes.", "tags": ["Workflows"], "security": [ { "bearerAuth": [] } ], "x-scope": "workflows:write", "x-rate-limit-bucket": "writes", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Optional. When sent, retries with the same key and input replay the first result." } ], "responses": { "204": { "description": "Done; no content.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{id}/pause": { "post": { "operationId": "pauseWorkflow", "summary": "Pause a workflow", "description": "Stops future processing. Content already handed to publishing is not recalled. An Idempotency-Key is optional and honored when sent. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: workflows:write. Rate bucket: writes.", "tags": ["Workflows"], "security": [ { "bearerAuth": [] } ], "x-scope": "workflows:write", "x-rate-limit-bucket": "writes", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Optional. When sent, retries with the same key and input replay the first result." } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{id}/resume": { "post": { "operationId": "resumeWorkflow", "summary": "Resume a workflow", "description": "Reactivates the workflow after re-checking your plan, both accounts and loops. An Idempotency-Key is optional and honored when sent. Non-final outcomes are not saved: errors returned before any change was made, every 429 and transient capacity or state conflicts (such as 409 POST_BUSY); retry those with the same key after Retry-After.\n\nScope: workflows:write. Rate bucket: writes.", "tags": ["Workflows"], "security": [ { "bearerAuth": [] } ], "x-scope": "workflows:write", "x-rate-limit-bucket": "writes", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Optional. When sent, retries with the same key and input replay the first result." } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } }, "Idempotency-Replayed": { "description": "true when this is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict: state does not allow the change, or idempotency conflict / unconfirmed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Content or destination not supported, or required consent missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "508": { "description": "The workflow would create a repost loop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{id}/activity": { "get": { "operationId": "getWorkflowActivity", "summary": "Get workflow activity", "description": "Source items being processed (including blocked items and the reason) and the posts the workflow created, newest first. Each list pages independently: pass processing.nextCursor as processingCursor and posts.nextCursor as postsCursor; limit applies to both. Media preparation is automatic.\n\nScope: workflows:read. Rate bucket: total only.", "tags": ["Workflows"], "security": [ { "bearerAuth": [] } ], "x-scope": "workflows:read", "x-rate-limit-bucket": "total", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "24-character hexadecimal ID.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–100, default 20).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "processingCursor", "in": "query", "required": false, "description": "Opaque nextCursor from the previous page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } }, { "name": "postsCursor", "in": "query", "required": false, "description": "Opaque nextCursor from the previous page.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": ["active", "paused"] }, "processing": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProcessingItem" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": ["data", "nextCursor"] }, "posts": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "nextCursor": { "type": "string", "nullable": true } }, "required": ["data", "nextCursor"] } }, "required": ["status", "processing", "posts"] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/summary": { "get": { "operationId": "getAnalyticsSummary", "summary": "Get analytics totals", "description": "Views, likes, comments, follower change and posts in the range, with the change against the previous range (null without a baseline) and lifetime totals. Stored observations, not a live platform refresh; may lag up to about an hour.\n\nScope: analytics:read. Rate bucket: analytics.", "tags": ["Analytics"], "security": [ { "bearerAuth": [] } ], "x-scope": "analytics:read", "x-rate-limit-bucket": "analytics", "parameters": [ { "name": "range", "in": "query", "required": false, "description": "Time window ending now.", "schema": { "type": "string", "enum": ["24h", "7d", "30d", "365d", "all"], "default": "30d" } }, { "name": "accountId", "in": "query", "required": false, "description": "Only this connected account.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "platform", "in": "query", "required": false, "description": "Only this platform.", "schema": { "type": "string", "enum": ["instagram", "facebook", "tiktok", "youtube", "threads"] } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "range": { "type": "string" }, "valueKind": { "type": "string", "nullable": true }, "totals": { "type": "object", "additionalProperties": false, "properties": { "views": { "type": "number" }, "likes": { "type": "number" }, "comments": { "type": "number" }, "followers": { "type": "number" }, "posts": { "type": "number" } }, "required": [ "views", "likes", "comments", "followers", "posts" ] }, "changePercent": { "type": "object", "additionalProperties": false, "properties": { "views": { "type": "number", "nullable": true }, "likes": { "type": "number", "nullable": true }, "comments": { "type": "number", "nullable": true }, "followers": { "type": "number", "nullable": true }, "posts": { "type": "number", "nullable": true } }, "required": [ "views", "likes", "comments", "followers", "posts" ] }, "lifetime": { "type": "object", "additionalProperties": false, "properties": { "views": { "type": "number" }, "likes": { "type": "number" }, "comments": { "type": "number" }, "posts": { "type": "number" } }, "required": ["views", "likes", "comments", "posts"], "nullable": true } }, "required": [ "range", "valueKind", "totals", "changePercent", "lifetime" ] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/timeseries": { "get": { "operationId": "getAnalyticsTimeseries", "summary": "Get a metric over time", "description": "Hourly (24h), daily (7d, 30d, 365d) or weekly (all, Monday-based) points of the observed change in one metric. Buckets start on hour/day/week boundaries in timezone: endAt (default now, at most one day ahead) is aligned down to the start of its bucket, and the last point is that (possibly partial) bucket. Stored observations; may lag up to about an hour.\n\nScope: analytics:read. Rate bucket: analytics.", "tags": ["Analytics"], "security": [ { "bearerAuth": [] } ], "x-scope": "analytics:read", "x-rate-limit-bucket": "analytics", "parameters": [ { "name": "metric", "in": "query", "required": true, "schema": { "type": "string", "enum": ["views", "likes", "comments", "followers"] } }, { "name": "range", "in": "query", "required": false, "description": "Time window ending now.", "schema": { "type": "string", "enum": ["24h", "7d", "30d", "365d", "all"], "default": "30d" } }, { "name": "accountId", "in": "query", "required": false, "description": "Only this connected account.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "platform", "in": "query", "required": false, "description": "Only this platform.", "schema": { "type": "string", "enum": ["instagram", "facebook", "tiktok", "youtube", "threads"] } }, { "name": "timezone", "in": "query", "required": false, "description": "Bucket boundaries' time zone (default UTC).", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "endAt", "in": "query", "required": false, "description": "Any time within the last bucket (default now); aligned down to its bucket start. ISO 8601 date-time with offset (e.g. 2026-11-01T09:00:00Z) or Unix milliseconds.", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "maxLength": 40 }, { "type": "integer", "minimum": 0, "maximum": 253402300799999 } ] } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "metric": { "type": "string" }, "range": { "type": "string" }, "timezone": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "at": { "type": "string", "format": "date-time" }, "value": { "type": "number" }, "increase": { "type": "number" }, "decrease": { "type": "number" }, "baseline": { "type": "number" }, "availableSamples": { "type": "integer" }, "unavailableSamples": { "type": "integer" } }, "required": [ "at", "value", "increase", "decrease", "baseline" ] } }, "coverage": { "type": "object", "additionalProperties": false, "properties": { "latestObservedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": ["latestObservedAt"] } }, "required": [ "metric", "range", "timezone", "points", "coverage" ] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/top-posts": { "get": { "operationId": "getTopPosts", "summary": "Get top posts", "description": "Posts ranked by observed view growth in the range. postId is the same ID as in /posts.\n\nScope: analytics:read. Rate bucket: analytics.", "tags": ["Analytics"], "security": [ { "bearerAuth": [] } ], "x-scope": "analytics:read", "x-rate-limit-bucket": "analytics", "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": ["24h", "7d", "30d"], "default": "7d" } }, { "name": "accountId", "in": "query", "required": false, "description": "Only this connected account.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "platform", "in": "query", "required": false, "description": "Only this platform.", "schema": { "type": "string", "enum": ["instagram", "facebook", "tiktok", "youtube", "threads"] } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "range": { "type": "string" }, "valueKind": { "type": "string", "nullable": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "postId": { "type": "string" }, "caption": { "type": "string" }, "thumbnailUrl": { "type": "string", "nullable": true }, "netViews": { "type": "number" }, "destinations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "accountName": { "type": "string", "nullable": true }, "platform": { "type": "string" }, "netViews": { "type": "number", "nullable": true }, "lastCheckedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "accountId", "accountName", "platform", "netViews", "lastCheckedAt" ] } } }, "required": [ "postId", "caption", "thumbnailUrl", "netViews", "destinations" ] } } }, "required": ["range", "valueKind", "data"] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/best-times": { "get": { "operationId": "getBestPostingTimes", "summary": "Get audience activity by hour of day", "description": "Observed view growth across your accounts grouped by the hour of day (0–23) in which it was recorded, in the given time zone (using the zone's current UTC offset). It shows when your audience watches, which you can use to choose posting times; it is not grouped by when posts were published. Baseline readings are excluded.\n\nScope: analytics:read. Rate bucket: analytics.", "tags": ["Analytics"], "security": [ { "bearerAuth": [] } ], "x-scope": "analytics:read", "x-rate-limit-bucket": "analytics", "parameters": [ { "name": "range", "in": "query", "required": false, "description": "Time window ending now.", "schema": { "type": "string", "enum": ["24h", "7d", "30d", "365d", "all"], "default": "30d" } }, { "name": "accountId", "in": "query", "required": false, "description": "Only this connected account.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "platform", "in": "query", "required": false, "description": "Only this platform.", "schema": { "type": "string", "enum": ["instagram", "facebook", "tiktok", "youtube", "threads"] } }, { "name": "timezone", "in": "query", "required": false, "description": "Time zone of the hours (default UTC).", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "description": "Identifies this HTTP attempt.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Total requests allowed this UTC minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Total requests left this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix seconds when the minute window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "range": { "type": "string" }, "timezone": { "type": "string" }, "hours": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "hour": { "type": "integer" }, "value": { "type": "number" } }, "required": ["hour", "value"] } } }, "required": ["range", "timezone", "hours"] } } } }, "400": { "description": "Invalid request (details.fields names each problem)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (INSUFFICIENT_SCOPE) or no paid plan (PLAN_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found among your resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or upload capacity reached; wait for Retry-After", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable or outcome unconfirmed; check the resource before retrying a mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }