{ "name": "Caroush MCP", "version": "1.0.0", "transport": "streamable_http", "endpoint": "https://mcp.caroush.com/mcp", "issuer": "https://app.caroush.com", "scopes": { "read:profile": "Read your profile and credit balance", "read:workspaces": "Read the workspace you authorize", "read:social": "List your connected social accounts (without credentials)", "read:content": "Read and search your posts, drafts and carousels", "create:content": "Create draft posts using text or existing media", "delete:content": "Request deletion of your content (requires approval)", "read:media": "Read your media library", "read:products": "Read your products and editorial profiles", "create:products": "Add products to your workspace", "manage:products": "Create and update your products", "delete:products": "Request deletion of products (requires approval)", "create:carousels": "Generate carousels using your credits", "manage:carousels": "Regenerate and approve carousels using your credits", "create:captions": "Generate caption, hook and hashtag variations", "read:schedules": "Read your publishing schedules", "publish:posts": "Request publication to social accounts (requires approval)", "publish:schedules": "Request scheduled publication (requires approval)", "read:automations": "Read automation settings and run history", "create:automations": "Create paused generation automations", "manage:automations": "Edit or run automations (activation requires approval)", "delete:automations": "Request deletion of automations (requires approval)", "read:analytics": "Read stored real post analytics, subject to your plan", "read:jobs": "Check requests made by this connection" }, "tools": [ { "name": "approve_carousel", "category": "CAROUSELS", "description": "Mark a finished owned carousel as reviewed and ready to publish. This does not publish or schedule. Requires the user\u2019s approval in Caroush.", "scope": "manage:carousels", "read_only": false, "queued_handler": false, "browser_approval": true, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "create_automation", "category": "AUTOMATION", "description": "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\u201315 second stored video; carousel accepts an optional stored image CTA.", "scope": "create:automations", "read_only": false, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "create_image_post", "category": "CONTENT", "description": "Create an image post or carousel from 1\u201310 existing owned media image IDs, in the supplied order. No URLs are downloaded and no publication occurs.", "scope": "create:content", "read_only": false, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "create_product", "category": "PRODUCTS", "description": "Save a product and queue Caroush product analysis. Provide a meaningful description; audience and content themes are optional reviewed editorial preferences.", "scope": "create:products", "read_only": false, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "create_text_post", "category": "CONTENT", "description": "Save a text-only post in Caroush. This does not publish or schedule it and does not consume image credits.", "scope": "create:content", "read_only": false, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "delete_automation", "category": "AUTOMATION", "description": "Delete an automation after browser approval, cancel unfinished runs and preserve existing published output. Releases reserved credits for unfinished video generation.", "scope": "delete:automations", "read_only": false, "queued_handler": false, "browser_approval": true, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "delete_post", "category": "CONTENT", "description": "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.", "scope": "delete:content", "read_only": false, "queued_handler": false, "browser_approval": true, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "delete_product", "category": "PRODUCTS", "description": "Remove an owned product. Existing automation configurations depending on it can no longer generate new content. Requires browser approval.", "scope": "delete:products", "read_only": false, "queued_handler": false, "browser_approval": true, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "disable_automation", "category": "AUTOMATION", "description": "Pause future runs for an automation. Pausing remains available even if a referenced product or account was removed.", "scope": "manage:automations", "read_only": false, "queued_handler": false, "browser_approval": true, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "enable_automation", "category": "AUTOMATION", "description": "Enable a saved automation after browser approval. Validates subscription, credits, product, media and connected accounts. Finished TikTok content still requires per-post review.", "scope": "manage:automations", "read_only": false, "queued_handler": false, "browser_approval": true, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "fetch_product_details", "category": "PRODUCTS", "description": "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.", "scope": "create:products", "read_only": false, "queued_handler": true, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "generate_captions", "category": "AI", "description": "Generate and save 3\u20135 TikTok-focused caption variants with hooks, CTAs and hashtags through Caroush. Runs asynchronously; the source field distinguishes provider AI from the existing local fallback.", "scope": "create:captions", "read_only": false, "queued_handler": true, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "generate_carousel", "category": "CAROUSELS", "description": "Queue a real 3\u201310 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.", "scope": "create:carousels", "read_only": false, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "generate_ugc_hook", "category": "AI", "description": "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.", "scope": "create:captions", "read_only": false, "queued_handler": true, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "get_account_analytics", "category": "ANALYTICS", "description": "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.", "scope": "read:analytics", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "get_account_settings", "category": "ACCOUNT", "description": "Read your subscription tier, account-wide resource quotas and the effective permissions of this MCP connection.", "scope": "read:profile", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_automation", "category": "AUTOMATION", "description": "Read one automation\u2019s configuration and current runtime credit price. IDs are separate for carousel and video automations; specify kind.", "scope": "read:automations", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "automation_id": { "type": "integer", "minimum": 1 } }, "required": [ "kind", "automation_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_automation_run", "category": "AUTOMATION", "description": "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.", "scope": "read:automations", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "video", "carousel" ] }, "run_id": { "type": "integer", "minimum": 1 } }, "required": [ "kind", "run_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_automation_runs", "category": "AUTOMATION", "description": "Read a paginated history of one automation\u2019s runs and each publication destination. No provider calls or new jobs are started.", "scope": "read:automations", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "get_best_performing_content", "category": "ANALYTICS", "description": "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.", "scope": "read:analytics", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "get_carousel", "category": "CAROUSELS", "description": "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.", "scope": "read:content", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "post_id": { "type": "integer", "minimum": 1 } }, "required": [ "post_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_carousel_outline", "category": "CAROUSELS", "description": "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.", "scope": "read:content", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "run_id": { "type": "integer", "minimum": 1 } }, "required": [ "run_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_credit_balance", "category": "ACCOUNT", "description": "Read the current credit balance, earned/spent totals and runtime price per generated image. Reads do not spend credits.", "scope": "read:profile", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_job_status", "category": "JOBS", "description": "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.", "scope": "read:jobs", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid" } }, "required": [ "operation_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_media", "category": "MEDIA", "description": "Read one owned image/video asset by its media ID.", "scope": "read:media", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "asset_id": { "type": "integer", "minimum": 1 } }, "required": [ "asset_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_post", "category": "CONTENT", "description": "Read one owned post, its ordered assets and confirmed live post links. IDs from another user or workspace are rejected.", "scope": "read:content", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "post_id": { "type": "integer", "minimum": 1 } }, "required": [ "post_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_post_analytics", "category": "ANALYTICS", "description": "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.", "scope": "read:analytics", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "schedule_id": { "type": "integer", "minimum": 1 } }, "required": [ "schedule_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_product", "category": "PRODUCTS", "description": "Read one owned product and its reviewed audience/content preferences.", "scope": "read:products", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 } }, "required": [ "product_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_profile", "category": "ACCOUNT", "description": "Read your authenticated identity and onboarding status. No authentication secrets or billing customer IDs are returned.", "scope": "read:profile", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_schedule", "category": "SCHEDULING", "description": "Read one publishing delivery, including its real permalink when available. schedule_id is a delivery ID, not a generated post ID.", "scope": "read:schedules", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "schedule_id": { "type": "integer", "minimum": 1 } }, "required": [ "schedule_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "get_workspace", "category": "ACCOUNT", "description": "Read the workspace chosen during OAuth consent. This never changes the workspace selected in your browser.", "scope": "read:workspaces", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "list_automations", "category": "AUTOMATION", "description": "List saved carousel or video generation automations. Video includes 2\u00d72, single fade and AI UGC. These schedules support daily times in an IANA timezone.", "scope": "read:automations", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "list_carousel_formats", "category": "CAROUSELS", "description": "List Caroush\u2019s currently supported carousel design systems and slide roles. Use these IDs when generating; retired designs are not accepted.", "scope": "read:content", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "list_connected_social_accounts", "category": "SOCIAL", "description": "List connected accounts in the authorized workspace, including connection health. Credentials are never returned.", "scope": "read:social", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "instagram", "tiktok", "facebook", "linkedin", "twitter", "threads", "bluesky" ] } }, "required": [], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "list_drafts", "category": "CONTENT", "description": "List owned content that has never been scheduled to a destination. Generated images and caption variants can also be drafts.", "scope": "read:content", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "integer", "minimum": 1 } }, "required": [], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "list_media", "category": "MEDIA", "description": "List owned image/video assets already saved in Caroush. Returned media IDs can be used for image posts and CTA artwork.", "scope": "read:media", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "list_posts", "category": "CONTENT", "description": "List your saved Caroush content with cursor pagination. Status filters use destination delivery state; draft means never scheduled. Dates filter content creation time.", "scope": "read:content", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "list_product_assets", "category": "PRODUCTS", "description": "List existing reference images, screenshots and logos attached to an owned product.", "scope": "read:products", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 } }, "required": [ "product_id" ], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "list_products", "category": "PRODUCTS", "description": "List the products you own in the authorized workspace, including reviewed audiences and editorial content themes.", "scope": "read:products", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "integer", "minimum": 1 } }, "required": [], "additionalProperties": false }, "outputSchema": { "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" } } } } } }, { "name": "list_schedules", "category": "SCHEDULING", "description": "List this user\u2019s delivery records in the authorized workspace, filtered by platform, status, post, account or scheduled date. Reads saved records only.", "scope": "read:schedules", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "publish_post", "category": "SOCIAL", "description": "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.", "scope": "publish:posts", "read_only": false, "queued_handler": true, "browser_approval": true, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "regenerate_carousel", "category": "CAROUSELS", "description": "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.", "scope": "manage:carousels", "read_only": false, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "retry_carousel", "category": "CAROUSELS", "description": "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.", "scope": "manage:carousels", "read_only": false, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "run_automation", "category": "AUTOMATION", "description": "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.", "scope": "manage:automations", "read_only": false, "queued_handler": false, "browser_approval": true, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "schedule_post", "category": "SCHEDULING", "description": "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.", "scope": "publish:schedules", "read_only": false, "queued_handler": false, "browser_approval": true, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "search_media", "category": "SEARCH", "description": "Search owned saved image/video asset titles and captions. Returns IDs and existing public media URLs, never storage credentials or paths.", "scope": "read:media", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "search_posts", "category": "SEARCH", "description": "Search your saved post titles and briefs in the authorized workspace. Returns bounded content and delivery summaries.", "scope": "read:content", "read_only": true, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "update_automation", "category": "AUTOMATION", "description": "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.", "scope": "manage:automations", "read_only": false, "queued_handler": false, "browser_approval": true, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } }, { "name": "update_product", "category": "PRODUCTS", "description": "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.", "scope": "manage:products", "read_only": false, "queued_handler": false, "browser_approval": false, "inputSchema": { "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 }, "outputSchema": { "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" } } } } } } ] }