{ "openapi": "3.1.0", "info": { "title": "MirageCHAT Publishing API", "version": "1.0.0", "summary": "Post to Instagram, Facebook and TikTok from your own systems.", "description": "Upload media, create posts on the accounts a key may use, read their status and numbers, and receive signed webhooks. Keys are created by the workspace owner or an admin under Security › Developer › API Keys. TikTok: choose tiktok.mode approve_in_app (the owner approves in MirageCHAT), drafts (the video goes to the creator’s TikTok inbox), or direct — only with a key whose «TikTok direct» box the owner ticked under Security › Developer › API Keys, and with TikTok’s choices (privacy, interactions, commercial disclosure, music confirmation) in every request. Human reference: https://miragechat.io/developers/publishing/", "contact": { "name": "MirageCHAT", "url": "https://miragechat.io/developers/publishing/", "email": "info@miragechat.io" } }, "servers": [ { "url": "https://miragechat.io/api/ext/v1" } ], "security": [ { "bearerKey": [] } ], "tags": [ { "name": "Accounts" }, { "name": "Media" }, { "name": "Posts" }, { "name": "Insights" }, { "name": "Music" }, { "name": "Hashtags" } ], "paths": { "/capabilities": { "get": { "tags": [ "Accounts" ], "operationId": "getCapabilities", "summary": "The accounts this key can post to", "description": "Scope: publish:read.", "responses": { "200": { "description": "One entry per account the key may use.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accounts" ], "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } }, "default_tiktok_mode": { "type": "string", "enum": [ "approve_in_app", "drafts", "direct" ] }, "tiktok_direct": { "type": "boolean", "description": "This key’s «TikTok direct» box." } } } } } }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "429": { "$ref": "#/components/responses/rate_limited" }, "500": { "$ref": "#/components/responses/internal_error" } } } }, "/media": { "post": { "tags": [ "Media" ], "operationId": "createMedia", "summary": "Upload a file or fetch a public https URL", "description": "Scope: publish. Up to 500 MB. URLs must be public https; private, local and metadata addresses are refused.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } }, "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" } } } } } }, "responses": { "200": { "description": "The same file is already in the library: its media, with duplicate: true.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Media" }, { "type": "object", "required": [ "duplicate" ], "properties": { "duplicate": { "type": "boolean", "const": true } } } ] } } } }, "201": { "description": "Stored and checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Media" } } } }, "400": { "$ref": "#/components/responses/validation_failed" }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "413": { "$ref": "#/components/responses/payload_too_large" }, "429": { "$ref": "#/components/responses/rate_limited" }, "500": { "$ref": "#/components/responses/internal_error" }, "503": { "$ref": "#/components/responses/service_unavailable" } } } }, "/media/{id}": { "get": { "tags": [ "Media" ], "operationId": "getMedia", "summary": "One uploaded file", "description": "Scope: publish.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A media id (med_ and digits, e.g. med_4821).", "schema": { "type": "string", "pattern": "^med_[0-9]+$" } } ], "responses": { "200": { "description": "The file and its checks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Media" } } } }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not_found" }, "429": { "$ref": "#/components/responses/rate_limited" }, "500": { "$ref": "#/components/responses/internal_error" } } } }, "/posts": { "post": { "tags": [ "Posts" ], "operationId": "createPost", "summary": "Create a post on one or more accounts", "description": "Scope: publish. One item per account and format (plus a story item per also_story platform).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A retry with the same key and body returns the first post instead of posting twice.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCreate" } } } }, "responses": { "200": { "description": "The same Idempotency-Key and body: the post created the first time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "$ref": "#/components/responses/validation_failed" }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "409": { "$ref": "#/components/responses/idempotency_conflict" }, "413": { "$ref": "#/components/responses/payload_too_large" }, "422": { "$ref": "#/components/responses/unsupported_by_platform" }, "429": { "$ref": "#/components/responses/too_many" }, "500": { "$ref": "#/components/responses/internal_error" } } }, "get": { "tags": [ "Posts" ], "operationId": "listPosts", "summary": "Your posts, newest first", "description": "Scope: publish:read.", "parameters": [ { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "awaiting_approval", "sent_to_drafts", "publishing", "published", "failed", "cancelled" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "The posts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "posts" ], "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } } } }, "400": { "$ref": "#/components/responses/validation_failed" }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "429": { "$ref": "#/components/responses/rate_limited" }, "500": { "$ref": "#/components/responses/internal_error" } } } }, "/posts/{id}": { "get": { "tags": [ "Posts" ], "operationId": "getPost", "summary": "One post and the status of each item", "description": "Scope: publish:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A post id (pst_ and digits, e.g. pst_1204).", "schema": { "type": "string", "pattern": "^pst_[0-9]+$" } } ], "responses": { "200": { "description": "The post.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not_found" }, "429": { "$ref": "#/components/responses/rate_limited" }, "500": { "$ref": "#/components/responses/internal_error" } } }, "delete": { "tags": [ "Posts" ], "operationId": "cancelPost", "summary": "Cancel what has not been published yet", "description": "Scope: publish.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A post id (pst_ and digits, e.g. pst_1204).", "schema": { "type": "string", "pattern": "^pst_[0-9]+$" } } ], "responses": { "200": { "description": "The post after cancelling; published items stay published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not_found" }, "429": { "$ref": "#/components/responses/rate_limited" }, "500": { "$ref": "#/components/responses/internal_error" } } } }, "/posts/{id}/insights": { "get": { "tags": [ "Insights" ], "operationId": "getPostInsights", "summary": "The numbers of each published item", "description": "Scope: publish:read. Every metric of the platform is named; null where the platform gave none (never 0). Refreshed at most every five minutes.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A post id (pst_ and digits, e.g. pst_1204).", "schema": { "type": "string", "pattern": "^pst_[0-9]+$" } } ], "responses": { "200": { "description": "Per item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Insights" } } } }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not_found" }, "429": { "$ref": "#/components/responses/rate_limited" }, "500": { "$ref": "#/components/responses/internal_error" } } } }, "/music": { "get": { "tags": [ "Music" ], "operationId": "listMusic", "summary": "Sounds you can use, per platform", "description": "Scope: publish:read.", "parameters": [ { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "instagram", "tiktok" ] } }, { "name": "trending", "in": "query", "schema": { "type": "boolean" } }, { "name": "genre", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The sounds.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Sound" } } } } }, "400": { "$ref": "#/components/responses/validation_failed" }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "429": { "$ref": "#/components/responses/rate_limited" }, "500": { "$ref": "#/components/responses/internal_error" } } } }, "/accounts/{id}/hashtags": { "get": { "tags": [ "Hashtags" ], "operationId": "getHashtags", "summary": "The account’s own hashtags", "description": "Scope: publish:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A publishing account id, as GET /capabilities lists it.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "The hashtags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hashtags" } } } }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not_found" }, "429": { "$ref": "#/components/responses/rate_limited" }, "500": { "$ref": "#/components/responses/internal_error" } } }, "put": { "tags": [ "Hashtags" ], "operationId": "putHashtags", "summary": "Replace the account’s own hashtags", "description": "Scope: publish. What is not sent is not changed; [] clears the list. Words that are not hashtags are left out; at most 30 are kept.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A publishing account id, as GET /capabilities lists it.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "hashtags": { "oneOf": [ { "type": "array", "maxItems": 200, "items": { "type": "string", "maxLength": 200 } }, { "type": "string" } ] }, "use_group": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "As stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hashtags" } } } }, "400": { "$ref": "#/components/responses/validation_failed" }, "401": { "$ref": "#/components/responses/invalid_api_key" }, "402": { "$ref": "#/components/responses/module_required" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not_found" }, "413": { "$ref": "#/components/responses/payload_too_large" }, "429": { "$ref": "#/components/responses/rate_limited" }, "500": { "$ref": "#/components/responses/internal_error" } } } } }, "webhooks": { "post.queued": { "post": { "summary": "The post.queued event", "description": "Signed: X-Mirage-Signature: t=,v1=. Answer 2xx within 8 s; 3 attempts; the endpoint is switched off after 20 failures in a row.", "parameters": [ { "name": "X-Mirage-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Mirage-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "post.queued" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "responses": { "200": { "description": "Received." } } } }, "post.awaiting_approval": { "post": { "summary": "The post.awaiting_approval event", "description": "Signed: X-Mirage-Signature: t=,v1=. Answer 2xx within 8 s; 3 attempts; the endpoint is switched off after 20 failures in a row.", "parameters": [ { "name": "X-Mirage-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Mirage-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "post.awaiting_approval" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "responses": { "200": { "description": "Received." } } } }, "post.sent_to_drafts": { "post": { "summary": "The post.sent_to_drafts event", "description": "Signed: X-Mirage-Signature: t=,v1=. Answer 2xx within 8 s; 3 attempts; the endpoint is switched off after 20 failures in a row.", "parameters": [ { "name": "X-Mirage-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Mirage-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "post.sent_to_drafts" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "responses": { "200": { "description": "Received." } } } }, "post.published": { "post": { "summary": "The post.published event", "description": "Signed: X-Mirage-Signature: t=,v1=. Answer 2xx within 8 s; 3 attempts; the endpoint is switched off after 20 failures in a row.", "parameters": [ { "name": "X-Mirage-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Mirage-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "post.published" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "responses": { "200": { "description": "Received." } } } }, "post.failed": { "post": { "summary": "The post.failed event", "description": "Signed: X-Mirage-Signature: t=,v1=. Answer 2xx within 8 s; 3 attempts; the endpoint is switched off after 20 failures in a row.", "parameters": [ { "name": "X-Mirage-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Mirage-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "post.failed" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "responses": { "200": { "description": "Received." } } } }, "post.cancelled": { "post": { "summary": "The post.cancelled event", "description": "Signed: X-Mirage-Signature: t=,v1=. Answer 2xx within 8 s; 3 attempts; the endpoint is switched off after 20 failures in a row.", "parameters": [ { "name": "X-Mirage-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Mirage-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "post.cancelled" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "responses": { "200": { "description": "Received." } } } } }, "components": { "securitySchemes": { "bearerKey": { "type": "http", "scheme": "bearer", "bearerFormat": "mck_live_…", "description": "A key with the publish or publish:read scope." } }, "responses": { "invalid_api_key": { "description": "invalid_api_key — missing, wrong, revoked or expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "forbidden": { "description": "insufficient_scope · ip_not_allowed · account_not_allowed · consent_required · tiktok_direct_not_enabled (tiktok.mode direct on a key without «TikTok direct»).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "module_required": { "description": "module_required — the package does not include the Publishing API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "rate_limited": { "description": "rate_limited — more than 60 requests a minute with this key. See Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "too_many": { "description": "rate_limited (60 a minute per key, with Retry-After) or platform_limit (the account reached the platform’s limit; resets_at when known).", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/PlatformLimitError" } ] } } } }, "validation_failed": { "description": "validation_failed — problems lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "unsupported_by_platform": { "description": "unsupported_by_platform — the platform does not allow it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnsupportedError" } } } }, "idempotency_conflict": { "description": "idempotency_conflict — the key was used with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "not_found": { "description": "not_found — no such post, file or account for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "internal_error": { "description": "internal_error — try again in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "payload_too_large": { "description": "payload_too_large — the request body is larger than 256 KB. Send files as multipart to POST /media.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "service_unavailable": { "description": "service_unavailable — our media storage is nearly full, so new media is not taken right now. Try again later; media already uploaded is safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "ErrorCode": { "type": "string", "enum": [ "invalid_api_key", "insufficient_scope", "ip_not_allowed", "account_not_allowed", "consent_required", "module_required", "rate_limited", "validation_failed", "unsupported_by_platform", "platform_limit", "idempotency_conflict", "not_found", "internal_error", "payload_too_large", "service_unavailable", "tiktok_direct_not_enabled" ] }, "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" } }, "additionalProperties": true }, "ValidationError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "required": [ "problems" ], "properties": { "error": { "const": "validation_failed" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } ] }, "UnsupportedError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "const": "unsupported_by_platform" }, "platform": { "type": "string", "enum": [ "instagram", "facebook", "tiktok" ] }, "feature": { "type": "string" } } } ] }, "PlatformLimitError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "const": "platform_limit" }, "platform": { "type": "string", "enum": [ "instagram", "facebook", "tiktok" ] }, "account_id": { "type": "integer" }, "resets_at": { "type": [ "string", "null" ], "format": "date-time" } } } ] }, "Platform": { "type": "string", "enum": [ "instagram", "facebook", "tiktok" ] }, "Format": { "type": "string", "enum": [ "reel", "video", "photo", "carousel", "story" ] }, "Status": { "type": "string", "enum": [ "queued", "awaiting_approval", "sent_to_drafts", "publishing", "published", "failed", "cancelled" ] }, "Capability": { "type": "object", "required": [ "id", "platform", "formats" ], "properties": { "id": { "type": "integer" }, "platform": { "$ref": "#/components/schemas/Platform" }, "name": { "type": "string" }, "handle": { "type": [ "string", "null" ] }, "formats": { "type": "array", "items": { "$ref": "#/components/schemas/Format" } }, "music": { "description": "Where music can go: Instagram { \"reel\": true }, TikTok { \"video\": true }; false on Facebook.", "oneOf": [ { "type": "object", "additionalProperties": { "type": "boolean" } }, { "const": false } ] }, "limits": { "type": "object", "properties": { "remaining_today": { "type": [ "integer", "null" ] } }, "additionalProperties": true }, "missing_permissions": { "type": "array", "description": "What stops this account from publishing now, each with what to do.", "items": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "modes": { "type": "object", "description": "TikTok only: the places left on each route; direct.available = the key has «TikTok direct» on and the creator can post now.", "properties": { "approve_in_app": { "type": "object", "additionalProperties": true }, "drafts": { "type": "object", "additionalProperties": true }, "direct": { "type": "object", "properties": { "available": { "type": "boolean" } }, "additionalProperties": true } } }, "tiktok": { "type": "object", "description": "TikTok only: the creator_info the owner’s screen shows — choose a direct post’s settings from it.", "properties": { "privacy_level_options": { "type": "array", "items": { "type": "string", "enum": [ "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY" ] } }, "comment_disabled": { "type": "boolean" }, "duet_disabled": { "type": "boolean" }, "stitch_disabled": { "type": "boolean" }, "max_video_post_duration_sec": { "type": [ "integer", "null" ] }, "can_post": { "type": "boolean" } } } } }, "Media": { "type": "object", "required": [ "media_id", "kind" ], "properties": { "media_id": { "type": "string", "pattern": "^med_[0-9]+$" }, "kind": { "type": "string", "enum": [ "photo", "video" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "duration_s": { "type": [ "number", "null" ] }, "per_channel": { "type": "object", "additionalProperties": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } } } } } }, "PostCreate": { "type": "object", "required": [ "account_ids", "format" ], "properties": { "account_ids": { "type": "array", "minItems": 1, "items": { "type": "integer" } }, "format": { "$ref": "#/components/schemas/Format" }, "media": { "type": "array", "items": { "type": "string", "pattern": "^med_[0-9]+$" } }, "caption": { "type": "string" }, "captions": { "type": "object", "properties": { "instagram": { "type": "string" }, "facebook": { "type": "string" }, "tiktok": { "type": "string" } }, "additionalProperties": false }, "link": { "type": "object", "properties": { "facebook": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "hashtags": { "type": "object", "properties": { "own": { "type": "boolean" }, "extra": { "type": "array", "items": { "type": "string" } }, "max": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } } }, "sound": { "type": "object", "properties": { "instagram": { "type": "string" }, "tiktok": { "type": "string" } }, "additionalProperties": false }, "also_story": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "facebook" ] } }, "tiktok": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "approve_in_app", "drafts", "direct" ] }, "privacy_level": { "type": "string", "enum": [ "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY" ], "description": "Who can see it — required, never a default; one of the levels GET /capabilities lists for the account (tiktok.privacy_level_options)." }, "disable_comment": { "type": "boolean", "description": "Not sent = true (comments off). false turns comments on — refused (422) when the creator turned them off in TikTok." }, "disable_duet": { "type": "boolean", "description": "Not sent = true. false turns Duet on — videos only; refused when the creator turned it off." }, "disable_stitch": { "type": "boolean", "description": "Not sent = true. false turns Stitch on — videos only; refused when the creator turned it off." }, "commercial": { "type": "boolean", "description": "Disclose commercial content. On, it needs brand_organic_toggle or brand_content_toggle." }, "brand_organic_toggle": { "type": "boolean", "description": "Your brand — labelled «Promotional content»." }, "brand_content_toggle": { "type": "boolean", "description": "Branded content — labelled «Paid partnership»; never with SELF_ONLY." }, "music_confirmed": { "const": true, "description": "Agreement to TikTok’s Music Usage Confirmation — required." } }, "description": "mode approve_in_app | drafts: nothing else — the owner (or the creator) chooses. mode direct: the fields of TikTokDirect too, privacy_level and music_confirmed required. Left out: the key’s default mode." }, "schedule_at": { "type": "string", "format": "date-time" } } }, "Item": { "type": "object", "required": [ "id", "account_id", "platform", "format", "status" ], "properties": { "id": { "type": "string", "pattern": "^itm_[0-9]+$" }, "account_id": { "type": "integer" }, "platform": { "$ref": "#/components/schemas/Platform" }, "format": { "$ref": "#/components/schemas/Format" }, "status": { "$ref": "#/components/schemas/Status" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "platform_id": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Post": { "type": "object", "required": [ "id", "items" ], "properties": { "id": { "type": "string", "pattern": "^pst_[0-9]+$" }, "idempotency_key": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } }, "Insights": { "type": "object", "required": [ "post_id", "read_at", "items" ], "properties": { "post_id": { "type": "string", "pattern": "^pst_[0-9]+$" }, "read_at": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "required": [ "item_id", "account_id", "platform", "format", "status", "metrics" ], "properties": { "item_id": { "type": "string", "pattern": "^itm_[0-9]+$" }, "account_id": { "type": "integer" }, "platform": { "$ref": "#/components/schemas/Platform" }, "format": { "$ref": "#/components/schemas/Format" }, "status": { "$ref": "#/components/schemas/Status" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "permalink": { "type": [ "string", "null" ] }, "unavailable": { "type": [ "string", "null" ] }, "metrics": { "oneOf": [ { "$ref": "#/components/schemas/InstagramMetrics" }, { "$ref": "#/components/schemas/FacebookMetrics" }, { "$ref": "#/components/schemas/TikTokMetrics" } ] } } } } } }, "InstagramMetrics": { "type": "object", "required": [ "views", "reach", "likes", "comments", "shares", "saved" ], "additionalProperties": false, "properties": { "views": { "type": [ "integer", "null" ] }, "reach": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "comments": { "type": [ "integer", "null" ] }, "shares": { "type": [ "integer", "null" ] }, "saved": { "type": [ "integer", "null" ] } } }, "FacebookMetrics": { "type": "object", "required": [ "views", "reactions", "comments", "shares", "clicks" ], "additionalProperties": false, "properties": { "views": { "type": [ "integer", "null" ] }, "reactions": { "type": [ "integer", "null" ] }, "comments": { "type": [ "integer", "null" ] }, "shares": { "type": [ "integer", "null" ] }, "clicks": { "type": [ "integer", "null" ] } } }, "TikTokMetrics": { "type": "object", "required": [ "views", "likes", "comments", "shares" ], "additionalProperties": false, "properties": { "views": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "comments": { "type": [ "integer", "null" ] }, "shares": { "type": [ "integer", "null" ] } } }, "Sound": { "type": "object", "required": [ "id", "platform", "title" ], "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "instagram", "tiktok" ] }, "title": { "type": "string" }, "artist": { "type": [ "string", "null" ] }, "duration_s": { "type": [ "number", "null" ] }, "genre": { "type": [ "string", "null" ] }, "trending": { "type": "boolean" }, "commercial_ok": { "type": "boolean" } } }, "Hashtags": { "type": "object", "required": [ "account_id", "platform", "hashtags", "use_group", "max" ], "properties": { "account_id": { "type": "integer" }, "platform": { "$ref": "#/components/schemas/Platform" }, "hashtags": { "type": "array", "maxItems": 30, "items": { "type": "string", "pattern": "^#" } }, "use_group": { "type": "boolean" }, "max": { "type": "integer", "const": 30 } } }, "WebhookEnvelope": { "type": "object", "required": [ "id", "type", "created", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_" }, "type": { "type": "string", "enum": [ "post.queued", "post.awaiting_approval", "post.sent_to_drafts", "post.published", "post.failed", "post.cancelled" ] }, "created": { "type": "integer" }, "tenant_id": { "type": "integer" }, "data": { "$ref": "#/components/schemas/PostEvent" } } }, "PostEvent": { "type": "object", "required": [ "event", "post_id", "item_id", "account_id", "platform", "format", "status" ], "properties": { "event": { "type": "string", "enum": [ "post.queued", "post.awaiting_approval", "post.sent_to_drafts", "post.published", "post.failed", "post.cancelled" ] }, "post_id": { "type": [ "string", "null" ], "pattern": "^pst_[0-9]+$", "description": "The API post (pst_ and digits); null for a post made on the web or the phone." }, "item_id": { "type": "string", "pattern": "^itm_[0-9]+$" }, "idempotency_key": { "type": [ "string", "null" ] }, "account_id": { "type": "integer" }, "platform": { "$ref": "#/components/schemas/Platform" }, "format": { "$ref": "#/components/schemas/Format" }, "status": { "$ref": "#/components/schemas/Status" }, "platform_id": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "TikTokDirect": { "type": "object", "description": "The choices of a direct TikTok post — the same the account owner makes in MirageCHAT before approving one, checked the same way against TikTok’s creator_info of that moment. Only with tiktok.mode direct (or a key whose default is direct), on a key with «TikTok direct» on; the post then goes out without approval in MirageCHAT.", "required": [ "privacy_level", "music_confirmed" ], "properties": { "privacy_level": { "type": "string", "enum": [ "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY" ], "description": "Who can see it — required, never a default; one of the levels GET /capabilities lists for the account (tiktok.privacy_level_options)." }, "disable_comment": { "type": "boolean", "description": "Not sent = true (comments off). false turns comments on — refused (422) when the creator turned them off in TikTok." }, "disable_duet": { "type": "boolean", "description": "Not sent = true. false turns Duet on — videos only; refused when the creator turned it off." }, "disable_stitch": { "type": "boolean", "description": "Not sent = true. false turns Stitch on — videos only; refused when the creator turned it off." }, "commercial": { "type": "boolean", "description": "Disclose commercial content. On, it needs brand_organic_toggle or brand_content_toggle." }, "brand_organic_toggle": { "type": "boolean", "description": "Your brand — labelled «Promotional content»." }, "brand_content_toggle": { "type": "boolean", "description": "Branded content — labelled «Paid partnership»; never with SELF_ONLY." }, "music_confirmed": { "const": true, "description": "Agreement to TikTok’s Music Usage Confirmation — required." } } } } } }