# Caroush MCP tool reference Generated from the installed tool catalog. Every mutation requires a UUID idempotency key. A queued handler or native queued run is not finished content. See mcp.md for the full protocol and authentication guide. ## approve_carousel Mark a finished owned carousel as reviewed and ready to publish. This does not publish or schedule. Requires the user’s approval in Caroush. - Category: CAROUSELS - Scope: `manage:carousels` - Read only: no - Browser approval: required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "run_id": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "run_id", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "run_id": { "type": "integer", "minimum": 1 }, "approval_status": { "type": "string", "enum": [ "approved" ] } }, "required": [ "run_id", "approval_status" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## create_automation Create a draft generation automation using an existing product and connected accounts. Does not enable or run it. UGC requires cta_asset_id referencing an owned 3–15 second stored video; carousel accepts an optional stored image CTA. - Category: AUTOMATION - Scope: `create:automations` - Read only: no - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "configuration": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "product_id": { "type": "integer", "minimum": 1 }, "social_account_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true, "minItems": 1 }, "times": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } }, "timezone": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "grid-video", "fade-video", "ugc-video" ] }, "template_id": { "type": "string", "enum": [ "2x2-grid", "single-fade", "ugc-video" ] }, "scene_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "music_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "format_id": { "type": "string", "maxLength": 100 }, "slide_count": { "type": "integer", "minimum": 3, "maximum": 10 }, "aspect_ratio": { "type": "string", "enum": [ "4:5", "3:4", "9:16" ] }, "settings": { "type": "object", "properties": { "brief": { "type": "string", "maxLength": 1200 }, "goal": { "type": "string", "maxLength": 80 }, "tone": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 120 }, "cta_text": { "type": "string", "maxLength": 160 }, "topics": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 30 }, "cta": { "type": "string", "maxLength": 100 }, "language": { "type": "string", "maxLength": 60 }, "max_hashtags": { "type": "integer", "minimum": 0, "maximum": 30 }, "duration": { "type": "integer", "enum": [ 8, 12, 15 ] }, "fade_speed": { "type": "string", "enum": [ "normal", "fast", "faster" ] }, "volume": { "type": "integer", "minimum": 0, "maximum": 100 }, "presenter_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "maxLength": 100 } }, "text_template": { "type": "string", "maxLength": 60 }, "text_y": { "type": "integer", "minimum": 15, "maximum": 85 }, "text_size": { "type": "integer" }, "original_audio": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [ "name", "product_id", "social_account_ids", "times" ], "additionalProperties": false }, "cta_asset_id": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "kind", "configuration", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "automation": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "carousel", "video" ] }, "name": { "type": "string" }, "status": { "type": "string" }, "configuration": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "product_id": { "type": "integer", "minimum": 1 }, "social_account_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true, "minItems": 1 }, "times": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } }, "timezone": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "grid-video", "fade-video", "ugc-video" ] }, "template_id": { "type": "string", "enum": [ "2x2-grid", "single-fade", "ugc-video" ] }, "scene_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "music_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "format_id": { "type": "string", "maxLength": 100 }, "slide_count": { "type": "integer", "minimum": 3, "maximum": 10 }, "aspect_ratio": { "type": "string", "enum": [ "4:5", "3:4", "9:16" ] }, "settings": { "type": "object", "properties": { "brief": { "type": "string", "maxLength": 1200 }, "goal": { "type": "string", "maxLength": 80 }, "tone": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 120 }, "cta_text": { "type": "string", "maxLength": 160 }, "topics": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 30 }, "cta": { "type": "string", "maxLength": 100 }, "language": { "type": "string", "maxLength": 60 }, "max_hashtags": { "type": "integer", "minimum": 0, "maximum": 30 }, "duration": { "type": "integer", "enum": [ 8, 12, 15 ] }, "fade_speed": { "type": "string", "enum": [ "normal", "fast", "faster" ] }, "volume": { "type": "integer", "minimum": 0, "maximum": 100 }, "presenter_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "maxLength": 100 } }, "text_template": { "type": "string", "maxLength": 60 }, "text_y": { "type": "integer", "minimum": 15, "maximum": 85 }, "text_size": { "type": "integer" }, "original_audio": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "has_cta": { "type": "boolean" }, "credit_cost": { "type": "integer" }, "next_run_at": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "name", "status", "configuration", "has_cta", "credit_cost", "next_run_at", "last_run_at" ], "additionalProperties": false } }, "required": [ "automation" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## create_image_post Create an image post or carousel from 1–10 existing owned media image IDs, in the supplied order. No URLs are downloaded and no publication occurs. - Category: CONTENT - Scope: `create:content` - Read only: no - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "asset_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 10, "uniqueItems": true }, "caption": { "type": "string", "maxLength": 2200 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "asset_ids", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "content_type": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "generated_at": { "type": [ "string", "null" ] }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [], "additionalProperties": false } }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "social_account_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "scheduled_for": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false } }, "required": [ "post" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## create_product Save a product and queue Caroush product analysis. Provide a meaningful description; audience and content themes are optional reviewed editorial preferences. - Category: PRODUCTS - Scope: `create:products` - Read only: no - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 1000 }, "website_url": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2048 } ] }, "logo_url": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2048 } ] }, "target_audiences": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 500 } }, "content_types": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 160 } }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "name", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "target_audiences": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 500 } }, "content_types": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 160 } }, "analyzed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false }, "analysis_status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "product", "analysis_status" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## create_text_post Save a text-only post in Caroush. This does not publish or schedule it and does not consume image credits. - Category: CONTENT - Scope: `create:content` - Read only: no - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "caption": { "type": "string", "maxLength": 2200 }, "status": { "type": "string", "enum": [ "draft", "ready" ] }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "caption", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "content_type": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "generated_at": { "type": [ "string", "null" ] }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [], "additionalProperties": false } }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "social_account_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "scheduled_for": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false } }, "required": [ "post" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## delete_automation Delete an automation after browser approval, cancel unfinished runs and preserve existing published output. Releases reserved credits for unfinished video generation. - Category: AUTOMATION - Scope: `delete:automations` - Read only: no - Browser approval: required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "automation_id": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "kind", "automation_id", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "automation_id": { "type": "integer", "minimum": 1 } }, "required": [ "deleted", "kind", "automation_id" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## delete_post Permanently remove an owned Caroush content record, its local delivery/history records and unreferenced media files. Does not remove posts already published on social platforms. Requires browser approval. - Category: CONTENT - Scope: `delete:content` - Read only: no - Browser approval: required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "post_id": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "post_id", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "deleted_post_id": { "type": "integer", "minimum": 1 } }, "required": [ "deleted_post_id" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## delete_product Remove an owned product. Existing automation configurations depending on it can no longer generate new content. Requires browser approval. - Category: PRODUCTS - Scope: `delete:products` - Read only: no - Browser approval: required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "product_id", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "deleted_product_id": { "type": "integer", "minimum": 1 } }, "required": [ "deleted_product_id" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## disable_automation Pause future runs for an automation. Pausing remains available even if a referenced product or account was removed. - Category: AUTOMATION - Scope: `manage:automations` - Read only: no - Browser approval: required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "automation_id": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "kind", "automation_id", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "automation": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "carousel", "video" ] }, "name": { "type": "string" }, "status": { "type": "string" }, "configuration": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "product_id": { "type": "integer", "minimum": 1 }, "social_account_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true, "minItems": 1 }, "times": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } }, "timezone": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "grid-video", "fade-video", "ugc-video" ] }, "template_id": { "type": "string", "enum": [ "2x2-grid", "single-fade", "ugc-video" ] }, "scene_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "music_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "format_id": { "type": "string", "maxLength": 100 }, "slide_count": { "type": "integer", "minimum": 3, "maximum": 10 }, "aspect_ratio": { "type": "string", "enum": [ "4:5", "3:4", "9:16" ] }, "settings": { "type": "object", "properties": { "brief": { "type": "string", "maxLength": 1200 }, "goal": { "type": "string", "maxLength": 80 }, "tone": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 120 }, "cta_text": { "type": "string", "maxLength": 160 }, "topics": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 30 }, "cta": { "type": "string", "maxLength": 100 }, "language": { "type": "string", "maxLength": 60 }, "max_hashtags": { "type": "integer", "minimum": 0, "maximum": 30 }, "duration": { "type": "integer", "enum": [ 8, 12, 15 ] }, "fade_speed": { "type": "string", "enum": [ "normal", "fast", "faster" ] }, "volume": { "type": "integer", "minimum": 0, "maximum": 100 }, "presenter_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "maxLength": 100 } }, "text_template": { "type": "string", "maxLength": 60 }, "text_y": { "type": "integer", "minimum": 15, "maximum": 85 }, "text_size": { "type": "integer" }, "original_audio": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "has_cta": { "type": "boolean" }, "credit_cost": { "type": "integer" }, "next_run_at": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "name", "status", "configuration", "has_cta", "credit_cost", "next_run_at", "last_run_at" ], "additionalProperties": false } }, "required": [ "automation" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## enable_automation Enable a saved automation after browser approval. Validates subscription, credits, product, media and connected accounts. Finished TikTok content still requires per-post review. - Category: AUTOMATION - Scope: `manage:automations` - Read only: no - Browser approval: required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "automation_id": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "kind", "automation_id", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "automation": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "carousel", "video" ] }, "name": { "type": "string" }, "status": { "type": "string" }, "configuration": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "product_id": { "type": "integer", "minimum": 1 }, "social_account_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true, "minItems": 1 }, "times": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } }, "timezone": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "grid-video", "fade-video", "ugc-video" ] }, "template_id": { "type": "string", "enum": [ "2x2-grid", "single-fade", "ugc-video" ] }, "scene_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "music_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "format_id": { "type": "string", "maxLength": 100 }, "slide_count": { "type": "integer", "minimum": 3, "maximum": 10 }, "aspect_ratio": { "type": "string", "enum": [ "4:5", "3:4", "9:16" ] }, "settings": { "type": "object", "properties": { "brief": { "type": "string", "maxLength": 1200 }, "goal": { "type": "string", "maxLength": 80 }, "tone": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 120 }, "cta_text": { "type": "string", "maxLength": 160 }, "topics": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 30 }, "cta": { "type": "string", "maxLength": 100 }, "language": { "type": "string", "maxLength": 60 }, "max_hashtags": { "type": "integer", "minimum": 0, "maximum": 30 }, "duration": { "type": "integer", "enum": [ 8, 12, 15 ] }, "fade_speed": { "type": "string", "enum": [ "normal", "fast", "faster" ] }, "volume": { "type": "integer", "minimum": 0, "maximum": 100 }, "presenter_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "maxLength": 100 } }, "text_template": { "type": "string", "maxLength": 60 }, "text_y": { "type": "integer", "minimum": 15, "maximum": 85 }, "text_size": { "type": "integer" }, "original_audio": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "has_cta": { "type": "boolean" }, "credit_cost": { "type": "integer" }, "next_run_at": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "name", "status", "configuration", "has_cta", "credit_cost", "next_run_at", "last_run_at" ], "additionalProperties": false } }, "required": [ "automation" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## fetch_product_details Fetch a public HTTP/HTTPS product page and suggest its audience and content themes using the existing product analyzer. Returns suggestions without saving a product. Runs asynchronously. - Category: PRODUCTS - Scope: `create:products` - Read only: no - Browser approval: not required - Queued handler: yes ### Input schema ```json { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "url", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "details": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "website_url": { "type": "string", "maxLength": 2048 }, "target_audience": { "type": [ "string", "null" ] }, "content_types": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 160 } }, "editorial_status": { "type": "string", "enum": [ "suggested", "unavailable" ] } }, "required": [], "additionalProperties": false } }, "required": [ "details" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## generate_captions Generate and save 3–5 TikTok-focused caption variants with hooks, CTAs and hashtags through Caroush. Runs asynchronously; the source field distinguishes provider AI from the existing local fallback. - Category: AI - Scope: `create:captions` - Read only: no - Browser approval: not required - Queued handler: yes ### Input schema ```json { "type": "object", "properties": { "category": { "type": "string", "maxLength": 80 }, "goal": { "type": "string", "maxLength": 80 }, "tone": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 120 }, "variant_count": { "type": "integer", "enum": [ 3, 4, 5 ] }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "category", "goal", "tone", "audience", "variant_count", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "post_id": { "type": "integer", "minimum": 1 }, "source": { "type": [ "string", "null" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "hook": { "type": "string" }, "caption": { "type": "string" }, "cta": { "type": "string" }, "hashtags": { "type": "array", "maxItems": 6, "items": { "type": "string", "maxLength": 200 } }, "structure": { "type": "string" } }, "required": [], "additionalProperties": false } } }, "required": [ "post_id", "source", "variants" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## generate_carousel Queue a real 3–10 slide carousel for an owned product. Uses reviewed product audiences by default. Costs 5 credits per AI-generated image; an optional existing CTA image replaces the final generated slide. Poll get_carousel; creation does not publish. - Category: CAROUSELS - Scope: `create:carousels` - Read only: no - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "brief": { "type": "string", "maxLength": 1200 }, "goal": { "type": "string", "maxLength": 80 }, "tone": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 15029 }, "content_types": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 160 } }, "format_id": { "type": "string", "maxLength": 100 }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "social" ] }, "slide_count": { "type": "integer", "minimum": 3, "maximum": 10 }, "aspect_ratio": { "type": "string", "enum": [ "9:16", "4:5", "3:4" ] }, "cta_text": { "type": "string", "maxLength": 160 }, "cta_asset_id": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "product_id", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "carousel": { "type": "object", "properties": { "post_id": { "type": "integer" }, "run_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "generation_status": { "type": "string" }, "format_id": { "type": [ "string", "null" ] }, "aspect_ratio": { "type": "string" }, "total_slides": { "type": "integer" }, "generated_slides": { "type": "integer" }, "uploaded_slides": { "type": "integer" }, "approval_status": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 300 } }, "credit_balance": { "type": "integer" }, "progress": { "type": "object", "properties": { "percent": { "type": "integer" }, "label": { "type": "string" } }, "required": [], "additionalProperties": false }, "error_message": { "type": [ "string", "null" ] }, "can_retry": { "type": "boolean" }, "slides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "is_uploaded": { "type": "boolean" } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false }, "estimated_credits": { "type": "integer", "minimum": 0 } }, "required": [ "carousel", "estimated_credits" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## generate_ugc_hook Generate one concise on-screen UGC video hook from a creative brief using the same prompt as Studio. Runs asynchronously; returns text only and does not render or publish a video. - Category: AI - Scope: `create:captions` - Read only: no - Browser approval: not required - Queued handler: yes ### Input schema ```json { "type": "object", "properties": { "brief": { "type": "string", "maxLength": 500 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "brief", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 180 } }, "required": [ "text" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_account_analytics Read saved, real performance for posts published through Caroush in the authorized workspace. Pro is required. Days filters publication cohorts; metrics are lifetime totals at the last sync, with coverage and missing values preserved. - Category: ANALYTICS - Scope: `read:analytics` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "days": { "type": "string", "enum": [ "7", "30", "90", "all" ] }, "social_account_id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string", "enum": [ "instagram", "tiktok", "facebook", "linkedin", "twitter", "threads", "bluesky" ] }, "media_type": { "type": "string", "enum": [ "all", "photo", "video", "text" ] }, "granularity": { "type": "string", "enum": [ "daily", "weekly" ] }, "page": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "report": { "type": "object", "properties": { "days": { "type": [ "integer", "string" ], "enum": [ 7, 30, 90, "all" ] }, "selectedAccountId": { "type": [ "integer", "null" ] }, "mediaType": { "type": "string" }, "selectedProvider": { "type": "string" }, "granularity": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "provider": { "type": "string" }, "providerLabel": { "type": "string" }, "displayName": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "provider", "providerLabel", "displayName", "username", "avatarUrl" ], "additionalProperties": false } }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "postId": { "type": "integer" }, "title": { "type": "string" }, "caption": { "type": "string" }, "provider": { "type": "string" }, "providerLabel": { "type": "string" }, "accountId": { "type": [ "integer", "null" ] }, "accountName": { "type": "string" }, "mediaType": { "type": "string" }, "thumbnailUrl": { "type": [ "string", "null" ] }, "mediaUrl": { "type": [ "string", "null" ] }, "postUrl": { "type": [ "string", "null" ] }, "publishedAt": { "type": "string" }, "status": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "fetchedAt": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "description": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "value" ], "additionalProperties": false } } }, "required": [ "id", "postId", "title", "caption", "provider", "providerLabel", "accountId", "accountName", "mediaType", "thumbnailUrl", "mediaUrl", "postUrl", "publishedAt", "status", "message", "fetchedAt", "stale", "metrics" ], "additionalProperties": false } }, "topPosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "postId": { "type": "integer" }, "title": { "type": "string" }, "caption": { "type": "string" }, "provider": { "type": "string" }, "providerLabel": { "type": "string" }, "accountId": { "type": [ "integer", "null" ] }, "accountName": { "type": "string" }, "mediaType": { "type": "string" }, "thumbnailUrl": { "type": [ "string", "null" ] }, "mediaUrl": { "type": [ "string", "null" ] }, "postUrl": { "type": [ "string", "null" ] }, "publishedAt": { "type": "string" }, "status": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "fetchedAt": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "description": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "value" ], "additionalProperties": false } } }, "required": [ "id", "postId", "title", "caption", "provider", "providerLabel", "accountId", "accountName", "mediaType", "thumbnailUrl", "mediaUrl", "postUrl", "publishedAt", "status", "message", "fetchedAt", "stale", "metrics" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "perPage": { "type": "integer" }, "total": { "type": "integer" }, "lastPage": { "type": "integer" } }, "required": [ "page", "perPage", "total", "lastPage" ], "additionalProperties": false }, "summary": { "type": "object", "properties": { "published": { "type": "integer" }, "photos": { "type": "integer" }, "videos": { "type": "integer" }, "textPosts": { "type": "integer" }, "syncedPosts": { "type": "integer" }, "stalePosts": { "type": "integer" }, "oldestFetchedAt": { "type": [ "string", "null" ] }, "latestFetchedAt": { "type": [ "string", "null" ] }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "key", "label", "value", "reportingPosts" ], "additionalProperties": false } }, "comparisons": { "type": "object", "properties": { "views": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "impressions": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "reach": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "likes": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "comments": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "shares": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "reposts": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "saves": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "quotes": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "clicks": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "sends": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "average_views": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "engagement_rate": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false }, "published": { "type": "object", "properties": { "previousValue": { "type": [ "number", "null" ] }, "changePercent": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" }, "previousReportingPosts": { "type": "integer" } }, "required": [ "previousValue", "changePercent", "reportingPosts", "previousReportingPosts" ], "additionalProperties": false } }, "required": [ "views", "impressions", "reach", "likes", "comments", "shares", "reposts", "saves", "quotes", "clicks", "sends", "average_views", "engagement_rate", "published" ], "additionalProperties": false } }, "required": [ "published", "photos", "videos", "textPosts", "syncedPosts", "stalePosts", "oldestFetchedAt", "latestFetchedAt", "metrics", "comparisons" ], "additionalProperties": false }, "comparisonPeriod": { "type": [ "object", "null" ], "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "label": { "type": "string" }, "published": { "type": "integer" }, "syncedPosts": { "type": "integer" }, "metrics": { "type": "object", "properties": { "views": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "impressions": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "reach": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "likes": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "comments": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "shares": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "reposts": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "saves": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "quotes": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "clicks": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "sends": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false } }, "required": [ "views", "impressions", "reach", "likes", "comments", "shares", "reposts", "saves", "quotes", "clicks", "sends" ], "additionalProperties": false } }, "required": [ "date", "label", "published", "syncedPosts", "metrics" ], "additionalProperties": false } }, "activityTrend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "label": { "type": "string" }, "published": { "type": "integer" }, "syncedPosts": { "type": "integer" }, "metrics": { "type": "object", "properties": { "views": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "impressions": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "reach": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "likes": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "comments": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "shares": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "reposts": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "saves": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "quotes": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "clicks": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false }, "sends": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "reportingPosts": { "type": "integer" } }, "required": [ "value", "reportingPosts" ], "additionalProperties": false } }, "required": [ "views", "impressions", "reach", "likes", "comments", "shares", "reposts", "saves", "quotes", "clicks", "sends" ], "additionalProperties": false } }, "required": [ "date", "label", "published", "syncedPosts", "metrics" ], "additionalProperties": false } }, "activityCoverage": { "type": "object", "properties": { "observedPosts": { "type": "integer" }, "totalPosts": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "observedPosts", "totalPosts", "message" ], "additionalProperties": false }, "dataSource": { "type": "string", "const": "live" }, "demoAvailable": { "type": "boolean" }, "demoGeneratedAt": { "type": [ "string", "null" ] }, "syncSchedule": { "type": "object", "properties": { "time": { "type": "string" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string" } }, "required": [ "time", "timezone", "nextRunAt" ], "additionalProperties": false } }, "required": [ "days", "selectedAccountId", "mediaType", "selectedProvider", "granularity", "accounts", "posts", "topPosts", "pagination", "summary", "comparisonPeriod", "trend", "activityTrend", "activityCoverage", "dataSource", "demoAvailable", "demoGeneratedAt", "syncSchedule" ], "additionalProperties": false } }, "required": [ "report" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_account_settings Read your subscription tier, account-wide resource quotas and the effective permissions of this MCP connection. - Category: ACCOUNT - Scope: `read:profile` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": {}, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "slug", "name", "active" ], "additionalProperties": false }, "quotas": { "type": "object", "properties": { "owned_workspaces": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "remaining": { "type": [ "integer", "null" ] }, "overLimit": { "type": "boolean" } }, "required": [ "used", "limit", "remaining", "overLimit" ], "additionalProperties": false }, "automations": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "remaining": { "type": [ "integer", "null" ] }, "overLimit": { "type": "boolean" } }, "required": [ "used", "limit", "remaining", "overLimit" ], "additionalProperties": false }, "connected_accounts": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "remaining": { "type": [ "integer", "null" ] }, "overLimit": { "type": "boolean" } }, "required": [ "used", "limit", "remaining", "overLimit" ], "additionalProperties": false } }, "required": [ "owned_workspaces", "automations", "connected_accounts" ], "additionalProperties": false }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "plan", "quotas", "scopes" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_automation Read one automation’s configuration and current runtime credit price. IDs are separate for carousel and video automations; specify kind. - Category: AUTOMATION - Scope: `read:automations` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "automation_id": { "type": "integer", "minimum": 1 } }, "required": [ "kind", "automation_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "automation": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "carousel", "video" ] }, "name": { "type": "string" }, "status": { "type": "string" }, "configuration": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "product_id": { "type": "integer", "minimum": 1 }, "social_account_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true, "minItems": 1 }, "times": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } }, "timezone": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "grid-video", "fade-video", "ugc-video" ] }, "template_id": { "type": "string", "enum": [ "2x2-grid", "single-fade", "ugc-video" ] }, "scene_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "music_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "format_id": { "type": "string", "maxLength": 100 }, "slide_count": { "type": "integer", "minimum": 3, "maximum": 10 }, "aspect_ratio": { "type": "string", "enum": [ "4:5", "3:4", "9:16" ] }, "settings": { "type": "object", "properties": { "brief": { "type": "string", "maxLength": 1200 }, "goal": { "type": "string", "maxLength": 80 }, "tone": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 120 }, "cta_text": { "type": "string", "maxLength": 160 }, "topics": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 30 }, "cta": { "type": "string", "maxLength": 100 }, "language": { "type": "string", "maxLength": 60 }, "max_hashtags": { "type": "integer", "minimum": 0, "maximum": 30 }, "duration": { "type": "integer", "enum": [ 8, 12, 15 ] }, "fade_speed": { "type": "string", "enum": [ "normal", "fast", "faster" ] }, "volume": { "type": "integer", "minimum": 0, "maximum": 100 }, "presenter_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "maxLength": 100 } }, "text_template": { "type": "string", "maxLength": 60 }, "text_y": { "type": "integer", "minimum": 15, "maximum": 85 }, "text_size": { "type": "integer" }, "original_audio": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "has_cta": { "type": "boolean" }, "credit_cost": { "type": "integer" }, "next_run_at": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "name", "status", "configuration", "has_cta", "credit_cost", "next_run_at", "last_run_at" ], "additionalProperties": false } }, "required": [ "automation" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_automation_run Read progress of an existing native automation run, including generated post and publishing statuses. kind is carousel or video; run_id is not the automation ID. - Category: AUTOMATION - Scope: `read:automations` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "run_id": { "type": "integer", "minimum": 1 } }, "required": [ "kind", "run_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "automation_id": { "type": "integer" }, "status": { "type": "string" }, "stage": { "type": [ "string", "null" ] }, "generated_post_id": { "type": [ "integer", "null" ] }, "carousel_run_id": { "type": [ "integer", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] }, "requires_review": { "type": "boolean" }, "review_url": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "social_account_id": { "type": [ "integer", "null" ] }, "provider": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "id", "post_id", "social_account_id", "provider", "status", "scheduled_at", "published_at", "post_url", "error" ], "additionalProperties": false } } }, "required": [ "id", "kind", "automation_id", "status", "stage", "generated_post_id", "carousel_run_id", "scheduled_at", "started_at", "finished_at", "requires_review", "review_url", "destinations" ], "additionalProperties": false } }, "required": [ "run" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_automation_runs Read a paginated history of one automation’s runs and each publication destination. No provider calls or new jobs are started. - Category: AUTOMATION - Scope: `read:automations` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "automation_id": { "type": "integer", "minimum": 1 }, "page": { "type": "integer", "minimum": 1, "maximum": 10000 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "kind", "automation_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "automation_id": { "type": "integer" }, "status": { "type": "string" }, "stage": { "type": [ "string", "null" ] }, "generated_post_id": { "type": [ "integer", "null" ] }, "carousel_run_id": { "type": [ "integer", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] }, "requires_review": { "type": "boolean" }, "review_url": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "social_account_id": { "type": [ "integer", "null" ] }, "provider": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "id", "post_id", "social_account_id", "provider", "status", "scheduled_at", "published_at", "post_url", "error" ], "additionalProperties": false } } }, "required": [ "id", "kind", "automation_id", "status", "stage", "generated_post_id", "carousel_run_id", "scheduled_at", "started_at", "finished_at", "requires_review", "review_url", "destinations" ], "additionalProperties": false } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "runs", "page", "per_page", "total" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_best_performing_content Return up to five Caroush posts ranked by reported views in a publication-date cohort. Pro is required. Posts without available view metrics are excluded; comparisons across platforms have different view definitions. - Category: ANALYTICS - Scope: `read:analytics` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "days": { "type": "string", "enum": [ "7", "30", "90", "all" ] }, "social_account_id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string", "enum": [ "instagram", "tiktok", "facebook", "linkedin", "twitter", "threads", "bluesky" ] }, "media_type": { "type": "string", "enum": [ "all", "photo", "video", "text" ] } }, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "ranking_metric": { "type": "string", "const": "views" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "postId": { "type": "integer" }, "title": { "type": "string" }, "caption": { "type": "string" }, "provider": { "type": "string" }, "providerLabel": { "type": "string" }, "accountId": { "type": [ "integer", "null" ] }, "accountName": { "type": "string" }, "mediaType": { "type": "string" }, "thumbnailUrl": { "type": [ "string", "null" ] }, "mediaUrl": { "type": [ "string", "null" ] }, "postUrl": { "type": [ "string", "null" ] }, "publishedAt": { "type": "string" }, "status": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "fetchedAt": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "description": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "value" ], "additionalProperties": false } } }, "required": [ "id", "postId", "title", "caption", "provider", "providerLabel", "accountId", "accountName", "mediaType", "thumbnailUrl", "mediaUrl", "postUrl", "publishedAt", "status", "message", "fetchedAt", "stale", "metrics" ], "additionalProperties": false } }, "coverage_note": { "type": "string" } }, "required": [ "ranking_metric", "posts", "coverage_note" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_carousel Read an owned carousel by its post ID: saved slide images/copy, progress, errors, credit balance and approval state. A queued response is not finished content. - Category: CAROUSELS - Scope: `read:content` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "post_id": { "type": "integer", "minimum": 1 } }, "required": [ "post_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "carousel": { "type": "object", "properties": { "post_id": { "type": "integer" }, "run_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "generation_status": { "type": "string" }, "format_id": { "type": [ "string", "null" ] }, "aspect_ratio": { "type": "string" }, "total_slides": { "type": "integer" }, "generated_slides": { "type": "integer" }, "uploaded_slides": { "type": "integer" }, "approval_status": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 300 } }, "credit_balance": { "type": "integer" }, "progress": { "type": "object", "properties": { "percent": { "type": "integer" }, "label": { "type": "string" } }, "required": [], "additionalProperties": false }, "error_message": { "type": [ "string", "null" ] }, "can_retry": { "type": "boolean" }, "slides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "is_uploaded": { "type": "boolean" } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false } }, "required": [ "carousel" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_carousel_outline Read saved copy and slide roles from an owned carousel specification once its planning is complete. This performs no generation and exposes no internal storage paths or prompts. - Category: CAROUSELS - Scope: `read:content` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "run_id": { "type": "integer", "minimum": 1 } }, "required": [ "run_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "run_id": { "type": "integer", "minimum": 1 }, "format_id": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "slides": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "role": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "subheadline": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "cta": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false } } }, "required": [ "run_id", "format_id", "caption", "slides" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_credit_balance Read the current credit balance, earned/spent totals and runtime price per generated image. Reads do not spend credits. - Category: ACCOUNT - Scope: `read:profile` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": {}, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "balance": { "type": "integer" }, "lifetimeEarned": { "type": "integer" }, "lifetimeSpent": { "type": "integer" }, "costPerImage": { "type": "integer" } }, "required": [ "balance", "lifetimeEarned", "lifetimeSpent", "costPerImage" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_job_status Read an MCP operation created by this connection. Its result can contain a separate native carousel/automation run ID: poll that resource for generation or publication completion. Never assume queued work is finished. - Category: JOBS - Scope: `read:jobs` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" } }, "required": [ "operation_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "required": [ "operation_id", "status" ], "properties": { "operation_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "object" }, "approval_url": { "type": "string" } }, "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_media Read one owned image/video asset by its media ID. - Category: MEDIA - Scope: `read:media` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "asset_id": { "type": "integer", "minimum": 1 } }, "required": [ "asset_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "media": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [], "additionalProperties": false } }, "required": [ "media" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_post Read one owned post, its ordered assets and confirmed live post links. IDs from another user or workspace are rejected. - Category: CONTENT - Scope: `read:content` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "post_id": { "type": "integer", "minimum": 1 } }, "required": [ "post_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "content_type": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "generated_at": { "type": [ "string", "null" ] }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [], "additionalProperties": false } }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "social_account_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "scheduled_for": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false } }, "required": [ "post" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_post_analytics Read the latest saved metrics for one published Caroush delivery. Pro is required. schedule_id identifies a publication on one account. Does not fetch providers. - Category: ANALYTICS - Scope: `read:analytics` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "schedule_id": { "type": "integer", "minimum": 1 } }, "required": [ "schedule_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "integer" }, "postId": { "type": "integer" }, "title": { "type": "string" }, "caption": { "type": "string" }, "provider": { "type": "string" }, "providerLabel": { "type": "string" }, "accountId": { "type": [ "integer", "null" ] }, "accountName": { "type": "string" }, "mediaType": { "type": "string" }, "thumbnailUrl": { "type": [ "string", "null" ] }, "mediaUrl": { "type": [ "string", "null" ] }, "postUrl": { "type": [ "string", "null" ] }, "publishedAt": { "type": "string" }, "status": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "fetchedAt": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "description": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "value" ], "additionalProperties": false } } }, "required": [ "id", "postId", "title", "caption", "provider", "providerLabel", "accountId", "accountName", "mediaType", "thumbnailUrl", "mediaUrl", "postUrl", "publishedAt", "status", "message", "fetchedAt", "stale", "metrics" ], "additionalProperties": false } }, "required": [ "post" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_product Read one owned product and its reviewed audience/content preferences. - Category: PRODUCTS - Scope: `read:products` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 } }, "required": [ "product_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "target_audiences": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 500 } }, "content_types": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 160 } }, "analyzed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false } }, "required": [ "product" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_profile Read your authenticated identity and onboarding status. No authentication secrets or billing customer IDs are returned. - Category: ACCOUNT - Scope: `read:profile` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": {}, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "user_id": { "type": "integer" }, "name": { "type": "string" }, "onboarded": { "type": "boolean" } }, "required": [ "user_id", "name", "onboarded" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_schedule Read one publishing delivery, including its real permalink when available. schedule_id is a delivery ID, not a generated post ID. - Category: SCHEDULING - Scope: `read:schedules` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "schedule_id": { "type": "integer", "minimum": 1 } }, "required": [ "schedule_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "social_account_id": { "type": [ "integer", "null" ] }, "provider": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "id", "post_id", "social_account_id", "provider", "status", "scheduled_at", "published_at", "post_url", "error" ], "additionalProperties": false } }, "required": [ "schedule" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## get_workspace Read the workspace chosen during OAuth consent. This never changes the workspace selected in your browser. - Category: ACCOUNT - Scope: `read:workspaces` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": {}, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "workspace_id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "workspace_id", "name" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## list_automations List saved carousel or video generation automations. Video includes 2×2, single fade and AI UGC. These schedules support daily times in an IANA timezone. - Category: AUTOMATION - Scope: `read:automations` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused" ] }, "page": { "type": "integer", "minimum": 1, "maximum": 10000 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "kind" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "automations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "carousel", "video" ] }, "name": { "type": "string" }, "status": { "type": "string" }, "configuration": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "product_id": { "type": "integer", "minimum": 1 }, "social_account_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true, "minItems": 1 }, "times": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } }, "timezone": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "grid-video", "fade-video", "ugc-video" ] }, "template_id": { "type": "string", "enum": [ "2x2-grid", "single-fade", "ugc-video" ] }, "scene_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "music_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "format_id": { "type": "string", "maxLength": 100 }, "slide_count": { "type": "integer", "minimum": 3, "maximum": 10 }, "aspect_ratio": { "type": "string", "enum": [ "4:5", "3:4", "9:16" ] }, "settings": { "type": "object", "properties": { "brief": { "type": "string", "maxLength": 1200 }, "goal": { "type": "string", "maxLength": 80 }, "tone": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 120 }, "cta_text": { "type": "string", "maxLength": 160 }, "topics": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 30 }, "cta": { "type": "string", "maxLength": 100 }, "language": { "type": "string", "maxLength": 60 }, "max_hashtags": { "type": "integer", "minimum": 0, "maximum": 30 }, "duration": { "type": "integer", "enum": [ 8, 12, 15 ] }, "fade_speed": { "type": "string", "enum": [ "normal", "fast", "faster" ] }, "volume": { "type": "integer", "minimum": 0, "maximum": 100 }, "presenter_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "maxLength": 100 } }, "text_template": { "type": "string", "maxLength": 60 }, "text_y": { "type": "integer", "minimum": 15, "maximum": 85 }, "text_size": { "type": "integer" }, "original_audio": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "has_cta": { "type": "boolean" }, "credit_cost": { "type": "integer" }, "next_run_at": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "name", "status", "configuration", "has_cta", "credit_cost", "next_run_at", "last_run_at" ], "additionalProperties": false } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "automations", "page", "per_page", "total" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## list_carousel_formats List Caroush’s currently supported carousel design systems and slide roles. Use these IDs when generating; retired designs are not accepted. - Category: CAROUSELS - Scope: `read:content` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": {}, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "formats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "group": { "type": "string" }, "slide_count": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "recommended": { "type": "integer" } }, "required": [ "min", "max", "recommended" ], "additionalProperties": false }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [], "additionalProperties": false } } }, "required": [ "formats" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## list_connected_social_accounts List connected accounts in the authorized workspace, including connection health. Credentials are never returned. - Category: SOCIAL - Scope: `read:social` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "instagram", "tiktok", "facebook", "linkedin", "twitter", "threads", "bluesky" ] } }, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string", "enum": [ "instagram", "tiktok", "facebook", "linkedin", "twitter", "threads", "bluesky" ] }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "health_status": { "type": "string" } }, "required": [ "id", "provider", "display_name", "username", "avatar_url", "health_status" ], "additionalProperties": false } } }, "required": [ "accounts" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## list_drafts List owned content that has never been scheduled to a destination. Generated images and caption variants can also be drafts. - Category: CONTENT - Scope: `read:content` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "query": { "type": "string", "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "integer", "minimum": 1 } }, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "content_type": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "generated_at": { "type": [ "string", "null" ] }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [], "additionalProperties": false } }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "social_account_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "scheduled_for": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false } }, "next_cursor": { "type": [ "integer", "null" ] } }, "required": [ "items", "next_cursor" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## list_media List owned image/video assets already saved in Caroush. Returned media IDs can be used for image posts and CTA artwork. - Category: MEDIA - Scope: `read:media` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "query": { "type": "string", "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "integer", "minimum": 1 }, "post_id": { "type": "integer", "minimum": 1 }, "media_type": { "type": "string", "enum": [ "image", "video" ] } }, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [], "additionalProperties": false } }, "next_cursor": { "type": [ "integer", "null" ] } }, "required": [ "items", "next_cursor" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## list_posts List your saved Caroush content with cursor pagination. Status filters use destination delivery state; draft means never scheduled. Dates filter content creation time. - Category: CONTENT - Scope: `read:content` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "query": { "type": "string", "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "generated", "scheduled", "publishing", "published", "failed", "awaiting_review", "automation_pending" ] }, "platform": { "type": "string", "enum": [ "tiktok", "instagram", "facebook", "linkedin", "twitter", "threads", "bluesky" ] }, "content_type": { "type": "string", "enum": [ "text", "image", "carousel", "video", "story" ] }, "created_from": { "type": "string", "format": "date-time" }, "created_until": { "type": "string", "format": "date-time" } }, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "content_type": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "generated_at": { "type": [ "string", "null" ] }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [], "additionalProperties": false } }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "social_account_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "scheduled_for": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false } }, "next_cursor": { "type": [ "integer", "null" ] } }, "required": [ "items", "next_cursor" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## list_product_assets List existing reference images, screenshots and logos attached to an owned product. - Category: PRODUCTS - Scope: `read:products` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 } }, "required": [ "product_id" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "kind": { "type": "string", "maxLength": 40 }, "url": { "type": [ "string", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] } }, "required": [], "additionalProperties": false } } }, "required": [ "assets" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## list_products List the products you own in the authorized workspace, including reviewed audiences and editorial content themes. - Category: PRODUCTS - Scope: `read:products` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "query": { "type": "string", "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "integer", "minimum": 1 } }, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "target_audiences": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 500 } }, "content_types": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 160 } }, "analyzed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false } }, "next_cursor": { "type": [ "integer", "null" ] } }, "required": [ "items", "next_cursor" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## list_schedules List this user’s delivery records in the authorized workspace, filtered by platform, status, post, account or scheduled date. Reads saved records only. - Category: SCHEDULING - Scope: `read:schedules` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 10000 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 50 }, "status": { "type": "string", "enum": [ "scheduled", "publishing", "automation_pending", "awaiting_review", "published", "failed", "cancelled" ] }, "provider": { "type": "string", "enum": [ "instagram", "tiktok", "facebook", "linkedin", "twitter", "threads", "bluesky" ] }, "post_id": { "type": "integer", "minimum": 1 }, "social_account_id": { "type": "integer", "minimum": 1 }, "from": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" } }, "required": [], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "schedules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "social_account_id": { "type": [ "integer", "null" ] }, "provider": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "id", "post_id", "social_account_id", "provider", "status", "scheduled_at", "published_at", "post_url", "error" ], "additionalProperties": false } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "schedules", "page", "per_page", "total" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## publish_post Publish an existing approved post to connected accounts after browser approval. Publication runs in the background; provider processing may remain pending. TikTok must use the Caroush review composer. - Category: SOCIAL - Scope: `publish:posts` - Read only: no - Browser approval: required - Queued handler: yes ### Input schema ```json { "type": "object", "properties": { "post_id": { "type": "integer", "minimum": 1 }, "social_account_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 12, "uniqueItems": true }, "caption": { "type": "string", "maxLength": 3000 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "post_id", "social_account_ids", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "schedules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string", "enum": [ "instagram", "tiktok", "facebook", "linkedin", "twitter", "threads", "bluesky" ] }, "socialAccountId": { "type": "integer", "minimum": 1 }, "accountLabel": { "type": [ "string", "null" ] }, "scheduledFor": { "type": "string" }, "status": { "type": "string" }, "postUrl": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } }, "required": [ "id", "provider", "socialAccountId", "accountLabel", "scheduledFor", "status", "postUrl", "message" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "published": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "awaiting_review": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "published", "pending", "awaiting_review", "failed" ], "additionalProperties": false } }, "required": [ "message", "schedules" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## regenerate_carousel Queue a revision of an owned carousel. Targets slide/image require slide_index; other targets forbid it. New images cost 5 credits each; copy/hook/layout reuse images. Uploaded CTA artwork cannot be regenerated. Existing images remain available on failure. - Category: CAROUSELS - Scope: `manage:carousels` - Read only: no - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "run_id": { "type": "integer", "minimum": 1 }, "target": { "type": "string", "enum": [ "hook", "slide", "copy", "visual", "image", "layout", "all" ] }, "slide_index": { "type": "integer", "minimum": 1, "maximum": 10 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "run_id", "target", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "carousel": { "type": "object", "properties": { "post_id": { "type": "integer" }, "run_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "generation_status": { "type": "string" }, "format_id": { "type": [ "string", "null" ] }, "aspect_ratio": { "type": "string" }, "total_slides": { "type": "integer" }, "generated_slides": { "type": "integer" }, "uploaded_slides": { "type": "integer" }, "approval_status": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 300 } }, "credit_balance": { "type": "integer" }, "progress": { "type": "object", "properties": { "percent": { "type": "integer" }, "label": { "type": "string" } }, "required": [], "additionalProperties": false }, "error_message": { "type": [ "string", "null" ] }, "can_retry": { "type": "boolean" }, "slides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "is_uploaded": { "type": "boolean" } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false }, "revision_id": { "type": "integer", "minimum": 1 }, "credits_charged": { "type": "integer", "minimum": 0 } }, "required": [ "carousel", "revision_id", "credits_charged" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## retry_carousel Resume an eligible failed original carousel from saved checkpoints. Reuses reserved credits or charges refunded credits again according to the existing recovery rules. Poll get_carousel for completion. - Category: CAROUSELS - Scope: `manage:carousels` - Read only: no - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "run_id": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "run_id", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "carousel": { "type": "object", "properties": { "post_id": { "type": "integer" }, "run_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "generation_status": { "type": "string" }, "format_id": { "type": [ "string", "null" ] }, "aspect_ratio": { "type": "string" }, "total_slides": { "type": "integer" }, "generated_slides": { "type": "integer" }, "uploaded_slides": { "type": "integer" }, "approval_status": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 300 } }, "credit_balance": { "type": "integer" }, "progress": { "type": "object", "properties": { "percent": { "type": "integer" }, "label": { "type": "string" } }, "required": [], "additionalProperties": false }, "error_message": { "type": [ "string", "null" ] }, "can_retry": { "type": "boolean" }, "slides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "is_uploaded": { "type": "boolean" } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false }, "credits_charged": { "type": "integer", "minimum": 0 } }, "required": [ "carousel", "credits_charged" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## run_automation Queue one real generation-and-publishing occurrence after browser approval. Uses the request idempotency key to reuse the same native run on retries. Poll get_automation_run for completion; TikTok output requires browser review. - Category: AUTOMATION - Scope: `manage:automations` - Read only: no - Browser approval: required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "automation_id": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "kind", "automation_id", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "automation_id": { "type": "integer" }, "status": { "type": "string" }, "stage": { "type": [ "string", "null" ] }, "generated_post_id": { "type": [ "integer", "null" ] }, "carousel_run_id": { "type": [ "integer", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] }, "requires_review": { "type": "boolean" }, "review_url": { "type": [ "string", "null" ] }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "social_account_id": { "type": [ "integer", "null" ] }, "provider": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "id", "post_id", "social_account_id", "provider", "status", "scheduled_at", "published_at", "post_url", "error" ], "additionalProperties": false } } }, "required": [ "id", "kind", "automation_id", "status", "stage", "generated_post_id", "carousel_run_id", "scheduled_at", "started_at", "finished_at", "requires_review", "review_url", "destinations" ], "additionalProperties": false } }, "required": [ "run" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## schedule_post Schedule an existing approved post to connected accounts. Requires browser approval. TikTok must be reviewed and submitted in the Caroush composer; this tool never supplies TikTok consent. - Category: SCHEDULING - Scope: `publish:schedules` - Read only: no - Browser approval: required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "post_id": { "type": "integer", "minimum": 1 }, "caption": { "type": "string", "maxLength": 3000 }, "timezone": { "type": "string" }, "destinations": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "object", "properties": { "social_account_id": { "type": "integer", "minimum": 1 }, "scheduled_at": { "type": "string", "format": "date-time" }, "caption": { "type": "string", "maxLength": 3000 } }, "required": [ "social_account_id", "scheduled_at" ], "additionalProperties": false } }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "post_id", "destinations", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "schedules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string", "enum": [ "instagram", "tiktok", "facebook", "linkedin", "twitter", "threads", "bluesky" ] }, "socialAccountId": { "type": "integer", "minimum": 1 }, "accountLabel": { "type": [ "string", "null" ] }, "scheduledFor": { "type": "string" }, "status": { "type": "string" }, "postUrl": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } }, "required": [ "id", "provider", "socialAccountId", "accountLabel", "scheduledFor", "status", "postUrl", "message" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "published": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "awaiting_review": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": [ "published", "pending", "awaiting_review", "failed" ], "additionalProperties": false } }, "required": [ "message", "schedules" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## search_media Search owned saved image/video asset titles and captions. Returns IDs and existing public media URLs, never storage credentials or paths. - Category: SEARCH - Scope: `read:media` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "query": { "type": "string", "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "integer", "minimum": 1 }, "post_id": { "type": "integer", "minimum": 1 }, "media_type": { "type": "string", "enum": [ "image", "video" ] } }, "required": [ "query" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [], "additionalProperties": false } }, "next_cursor": { "type": [ "integer", "null" ] } }, "required": [ "items", "next_cursor" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## search_posts Search your saved post titles and briefs in the authorized workspace. Returns bounded content and delivery summaries. - Category: SEARCH - Scope: `read:content` - Read only: yes - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "query": { "type": "string", "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "generated", "scheduled", "publishing", "published", "failed", "awaiting_review", "automation_pending" ] }, "platform": { "type": "string", "enum": [ "tiktok", "instagram", "facebook", "linkedin", "twitter", "threads", "bluesky" ] }, "content_type": { "type": "string", "enum": [ "text", "image", "carousel", "video", "story" ] }, "created_from": { "type": "string", "format": "date-time" }, "created_until": { "type": "string", "format": "date-time" } }, "required": [ "query" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "content_type": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "generated_at": { "type": [ "string", "null" ] }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "poster_url": { "type": [ "string", "null" ] }, "position": { "type": "integer" } }, "required": [], "additionalProperties": false } }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "social_account_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "scheduled_for": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false } }, "next_cursor": { "type": [ "integer", "null" ] } }, "required": [ "items", "next_cursor" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## update_automation Update a saved generation automation while preserving omitted settings. Browser approval is required because an active definition controls future publishing. CTA must be an owned stored asset. - Category: AUTOMATION - Scope: `manage:automations` - Read only: no - Browser approval: required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "automation_id": { "type": "integer", "minimum": 1 }, "configuration": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "product_id": { "type": "integer", "minimum": 1 }, "social_account_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true, "minItems": 1 }, "times": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } }, "timezone": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "grid-video", "fade-video", "ugc-video" ] }, "template_id": { "type": "string", "enum": [ "2x2-grid", "single-fade", "ugc-video" ] }, "scene_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "music_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "format_id": { "type": "string", "maxLength": 100 }, "slide_count": { "type": "integer", "minimum": 3, "maximum": 10 }, "aspect_ratio": { "type": "string", "enum": [ "4:5", "3:4", "9:16" ] }, "settings": { "type": "object", "properties": { "brief": { "type": "string", "maxLength": 1200 }, "goal": { "type": "string", "maxLength": 80 }, "tone": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 120 }, "cta_text": { "type": "string", "maxLength": 160 }, "topics": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 30 }, "cta": { "type": "string", "maxLength": 100 }, "language": { "type": "string", "maxLength": 60 }, "max_hashtags": { "type": "integer", "minimum": 0, "maximum": 30 }, "duration": { "type": "integer", "enum": [ 8, 12, 15 ] }, "fade_speed": { "type": "string", "enum": [ "normal", "fast", "faster" ] }, "volume": { "type": "integer", "minimum": 0, "maximum": 100 }, "presenter_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "maxLength": 100 } }, "text_template": { "type": "string", "maxLength": 60 }, "text_y": { "type": "integer", "minimum": 15, "maximum": 85 }, "text_size": { "type": "integer" }, "original_audio": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "cta_asset_id": { "type": "integer", "minimum": 1 }, "remove_cta": { "type": "boolean" }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "kind", "automation_id", "configuration", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "automation": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "carousel", "video" ] }, "name": { "type": "string" }, "status": { "type": "string" }, "configuration": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "product_id": { "type": "integer", "minimum": 1 }, "social_account_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true, "minItems": 1 }, "times": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } }, "timezone": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "grid-video", "fade-video", "ugc-video" ] }, "template_id": { "type": "string", "enum": [ "2x2-grid", "single-fade", "ugc-video" ] }, "scene_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "music_pool_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 30, "uniqueItems": true }, "format_id": { "type": "string", "maxLength": 100 }, "slide_count": { "type": "integer", "minimum": 3, "maximum": 10 }, "aspect_ratio": { "type": "string", "enum": [ "4:5", "3:4", "9:16" ] }, "settings": { "type": "object", "properties": { "brief": { "type": "string", "maxLength": 1200 }, "goal": { "type": "string", "maxLength": 80 }, "tone": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 120 }, "cta_text": { "type": "string", "maxLength": 160 }, "topics": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 30 }, "cta": { "type": "string", "maxLength": 100 }, "language": { "type": "string", "maxLength": 60 }, "max_hashtags": { "type": "integer", "minimum": 0, "maximum": 30 }, "duration": { "type": "integer", "enum": [ 8, 12, 15 ] }, "fade_speed": { "type": "string", "enum": [ "normal", "fast", "faster" ] }, "volume": { "type": "integer", "minimum": 0, "maximum": 100 }, "presenter_ids": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "maxLength": 100 } }, "text_template": { "type": "string", "maxLength": 60 }, "text_y": { "type": "integer", "minimum": 15, "maximum": 85 }, "text_size": { "type": "integer" }, "original_audio": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "has_cta": { "type": "boolean" }, "credit_cost": { "type": "integer" }, "next_run_at": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "name", "status", "configuration", "has_cta", "credit_cost", "next_run_at", "last_run_at" ], "additionalProperties": false } }, "required": [ "automation" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ``` ## update_product Update an owned product and queue fresh analysis. Name is required; omitted description and URL fields retain the existing values. Existing brand/features remain intact. - Category: PRODUCTS - Scope: `manage:products` - Read only: no - Browser approval: not required - Queued handler: no; inspect native status in the result ### Input schema ```json { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 1000 }, "website_url": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2048 } ] }, "logo_url": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2048 } ] }, "target_audiences": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 500 } }, "content_types": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 160 } }, "idempotency_key": { "type": "string", "format": "uuid", "description": "A new UUID per intended action. Reuse exactly for retries; never reuse with different arguments." } }, "required": [ "product_id", "name", "idempotency_key" ], "additionalProperties": false } ``` ### Output schema ```json { "type": "object", "additionalProperties": false, "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "succeeded", "queued", "running", "approval_required", "approved", "failed", "outcome_unknown", "denied", "dispatch_failed" ] }, "operation_id": { "type": "string", "format": "uuid" }, "approval_url": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "target_audiences": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 500 } }, "content_types": { "type": "array", "maxItems": 12, "items": { "type": "string", "maxLength": 160 } }, "analyzed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [], "additionalProperties": false }, "analysis_status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "product", "analysis_status" ], "additionalProperties": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } ```