{ "openapi": "3.0.0", "info": { "title": "ContentStudio API v1", "description": "ContentStudio API for managing content, social media, and workspace operations", "contact": { "name": "ContentStudio Support", "url": "https://docs.contentstudio.io", "email": "support@contentstudio.io" }, "license": { "name": "ContentStudio API License", "url": "https://contentstudio.io/terms-and-conditions" }, "version": "1.0.0" }, "paths": { "/api/v1/workspaces/{workspace_id}/accounts": { "get": { "tags": [ "πŸ“± Social Accounts" ], "summary": "Get social media accounts for a workspace", "description": "Retrieve paginated list of social media accounts for a specific workspace with optional platform filtering", "operationId": "1d4389fe8abb916ea97842ea8030f595", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "platform", "in": "query", "description": "Filter by platform(s). Use comma-separated values for multiple platforms", "required": false, "schema": { "type": "string", "enum": [ "facebook", "twitter", "linkedin", "pinterest", "instagram", "gmb", "youtube", "tiktok", "tumblr", "threads", "bluesky", "telegram" ], "example": "facebook,instagram,telegram" } }, { "name": "search", "in": "query", "description": "Search term to filter accounts by name (e.g. 'BloomVille', 'Hello Support')", "required": false, "schema": { "type": "string", "example": "BloomVille" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (max: 100)", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "example": 10 } } ], "responses": { "200": { "description": "Accounts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Accounts retrieved successfully" }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 25 }, "last_page": { "type": "integer", "example": 3 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 10 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Platform-specific account identifier", "type": "string", "example": "123456789" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "123456789", "deprecated": true }, "platform": { "type": "string", "enum": [ "facebook", "twitter", "linkedin", "pinterest", "instagram", "gmb", "youtube", "tiktok", "tumblr", "threads", "bluesky", "telegram" ], "example": "telegram" }, "account_name": { "type": "string", "example": "My Business Page" }, "profile_picture": { "type": "string", "example": "https://example.com/profile.jpg" }, "status": { "type": "string", "example": "active" }, "connected_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" }, "expires_at": { "type": "string", "format": "date-time", "example": "2024-03-15T10:30:00.000Z" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Workspace not found or access denied", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found or access denied" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/accounts/{account_id}": { "delete": { "tags": [ "πŸ“± Social Accounts" ], "summary": "Remove a social account", "description": "Disconnect (remove) a connected social account from the workspace. `account_id` is the account's `id` from GET /accounts. Requires the save_social permission.", "operationId": "removeAccount", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "account_id", "in": "path", "description": "Account `id` (platform identifier) from GET /accounts", "required": true, "schema": { "type": "string", "example": "350830594784444" } } ], "responses": { "200": { "description": "Account removed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Social account removed successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Insufficient permissions" } }, "type": "object" } } } }, "404": { "description": "Account not found in this workspace", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Account not found in this workspace" } }, "type": "object" } } } }, "422": { "description": "Failed to remove account", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to remove account" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/add/bluesky": { "post": { "tags": [ "πŸ”— Account Connection" ], "summary": "Connect a Bluesky account with credentials", "description": "Connects a Bluesky profile using a handle and app password. No browser step is required.", "operationId": "addBlueskyAccount", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "handle", "app_password" ], "properties": { "handle": { "type": "string", "maxLength": 255, "example": "yourname.bsky.social" }, "app_password": { "type": "string", "example": "xxxx-xxxx-xxxx-xxxx" } }, "type": "object" } } } }, "responses": { "200": { "description": "Bluesky account connected successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Bluesky account 'yourname.bsky.social' connected successfully." }, "data": { "properties": { "account_id": { "type": "string", "example": "610a1e660cb41530ca40d372" }, "platform": { "type": "string", "example": "bluesky" }, "account_name": { "type": "string", "example": "Your Display Name" }, "handle": { "type": "string", "example": "yourname.bsky.social" }, "profile_picture": { "type": "string", "example": "https://cdn.bsky.social/...", "nullable": true }, "status": { "type": "string", "example": "active" }, "connected_at": { "type": "string", "format": "date-time", "example": "2026-04-16T12:00:00Z" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid Bluesky credentials", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to authenticate with Bluesky. Please verify your handle and app password." }, "error_code": { "type": "string", "example": "INVALID_CREDENTIALS" }, "help": { "properties": { "handle_format": { "type": "string", "example": "Your handle looks like yourname.bsky.social or a custom domain." }, "app_password_steps": { "type": "array", "items": { "type": "string", "example": "Go to https://bsky.app/settings/app-passwords" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Forbidden or account limit reached. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Your workspace has reached the maximum number of connected social accounts. Upgrade your plan to add more." }, "error_code": { "type": "string", "example": "ACCOUNT_LIMIT_REACHED" } }, "type": "object" } } } }, "409": { "description": "Duplicate account", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Bluesky account 'yourname.bsky.social' is already connected to this workspace." }, "error_code": { "type": "string", "example": "DUPLICATE_ACCOUNT" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The handle field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/add/facebook-group": { "post": { "tags": [ "πŸ”— Account Connection" ], "summary": "Add a Facebook Group manually", "description": "Adds a Facebook Group connection using its name and an optional image URL. No browser step is required.", "operationId": "addFacebookGroupAccount", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 3, "example": "My Facebook Group" }, "image": { "type": "string", "format": "uri", "example": "https://example.com/group.jpg", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Facebook Group added successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Facebook Group 'My Facebook Group' added successfully." }, "data": { "properties": { "account_id": { "type": "string", "example": "610a1e660cb41530ca40d372" }, "platform": { "type": "string", "example": "facebook" }, "account_type": { "type": "string", "example": "group" }, "account_name": { "type": "string", "example": "My Facebook Group" }, "profile_picture": { "type": "string", "example": "https://example.com/group.jpg", "nullable": true }, "status": { "type": "string", "example": "active" }, "connected_at": { "type": "string", "format": "date-time", "example": "2026-04-16T12:00:00Z" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Forbidden or account limit reached. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You do not have permission to connect social accounts to this workspace." }, "error_code": { "type": "string", "example": "INSUFFICIENT_PERMISSIONS" } }, "type": "object" } } } }, "409": { "description": "Duplicate Facebook Group", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A Facebook Group with the name 'My Facebook Group' already exists in this workspace." }, "error_code": { "type": "string", "example": "DUPLICATE_ACCOUNT" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/carousels/templates": { "get": { "tags": [ "🎠 AI Carousels" ], "summary": "List carousel templates", "description": "Every library template, from the same source as the template picker in AI chat, with a cover preview. Pass an `id` as `style.template_id`.", "operationId": "listAiCarouselTemplates", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Templates retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "templates": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "clean-minimal" }, "name": { "type": "string", "example": "Clean Minimal" }, "best_for": { "type": "string", "example": "White space and one big sans, the key words swiped with a marker highlight." }, "sizes": { "type": "array", "items": { "type": "string", "enum": [ "portrait", "square" ] } }, "preview_url": { "description": "The cover as a PNG (1080x1350, default colours). Null for a few seconds after a deploy that changed the template.", "type": "string", "format": "url", "nullable": true }, "preview_html_url": { "description": "The same cover as HTML, for callers that recolour it with their brand.", "type": "string", "format": "url", "nullable": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "502": { "description": "AI service unavailable (`AI_SERVICE_UNAVAILABLE`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/carousels/estimate": { "post": { "tags": [ "🎠 AI Carousels" ], "summary": "Estimate a carousel's cost", "description": "The credit cost for these options. Nothing is generated or charged. A template deck has one price (`min` equals `max`). With mode auto or custom the AI picks the route while it plans (a template deck, a photo deck, or a deck drawn whole), so the cost is a range, and a generation never charges more than `max`.", "operationId": "estimateAiCarousel", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselOptions" }, "examples": { "auto": { "summary": "The AI picks the look", "value": { "prompt": "5 tips for better LinkedIn headlines", "slide_count": 6 } }, "template": { "summary": "A library template", "value": { "prompt": "5 tips for better LinkedIn headlines", "slide_count": 6, "size": "portrait", "style": { "mode": "template", "template_id": "clean-minimal" } } }, "custom_description": { "summary": "A look described in words", "value": { "prompt": "5 tips for better LinkedIn headlines", "style": { "mode": "custom", "description": "dark mode, neon accents" } } }, "custom_references": { "summary": "Match up to 2 images", "value": { "prompt": "5 tips for better LinkedIn headlines", "style": { "mode": "custom", "references": [ "https://example.com/reference.png" ] } } } } } } }, "responses": { "200": { "description": "Estimated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "properties": { "credits": { "properties": { "min": { "type": "integer", "example": 8 }, "max": { "type": "integer", "example": 8 } }, "type": "object" }, "route_known": { "description": "true when the price is exact (mode template).", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "`VALIDATION_ERROR`, `UNKNOWN_TEMPLATE`, `TOO_MANY_REFERENCES`, `SLIDE_COUNT_OUT_OF_RANGE` or `STYLE_FIELDS_CONFLICT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "502": { "description": "AI service unavailable (`AI_SERVICE_UNAVAILABLE`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/carousels/generate": { "post": { "tags": [ "🎠 AI Carousels" ], "summary": "Generate a carousel", "description": "Builds the carousel and answers when it is done, like image generation: about 25 seconds for a template, up to about 3 minutes for a deck the AI draws. The response holds the slides in order (each saved to the media library with a `media_id`), one `caption`, the `style` used, the `credits` charged and the `carousel_id` to edit. Pass the media IDs and caption to POST .../posts with post_type carousel. `failed_slots` lists slides that could not be drawn; only delivered slides are charged. A request that fails charges nothing. Allow at least 300 seconds before timing out: a client that gives up and retries starts, and pays for, a second carousel.", "operationId": "generateAiCarousel", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselOptions" }, "examples": { "auto": { "summary": "The AI picks the look", "value": { "prompt": "5 tips for better LinkedIn headlines", "slide_count": 6 } }, "template": { "summary": "A library template", "value": { "prompt": "5 tips for better LinkedIn headlines", "slide_count": 6, "size": "portrait", "style": { "mode": "template", "template_id": "clean-minimal" } } }, "custom_description": { "summary": "A look described in words", "value": { "prompt": "5 tips for better LinkedIn headlines", "style": { "mode": "custom", "description": "dark mode, neon accents" } } }, "custom_references": { "summary": "Match up to 2 images", "value": { "prompt": "5 tips for better LinkedIn headlines", "style": { "mode": "custom", "references": [ "https://example.com/reference.png" ] } } } } } } }, "responses": { "200": { "description": "The finished carousel", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/CarouselDeck" } }, "type": "object" } } } }, "403": { "description": "Out of AI image credits (`IMAGE_CREDIT_LIMIT_EXCEEDED`); out of API credits (`API_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "422": { "description": "`VALIDATION_ERROR`, `UNKNOWN_TEMPLATE`, `TOO_MANY_REFERENCES`, `REFERENCE_UNREADABLE`, `SLIDE_COUNT_OUT_OF_RANGE`, `STYLE_FIELDS_CONFLICT`, or `PROMPT_NEEDS_DETAIL` (the prompt gave no subject)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "429": { "description": "Too many carousels being made in this workspace at once (`CAROUSEL_REQUESTS_LIMIT`), or the rate limit (`RATE_LIMIT_EXCEEDED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "502": { "description": "Safe to retry: `CAROUSEL_GENERATION_FAILED`, `AI_SERVICE_UNAVAILABLE`, or `MEDIA_PERSISTENCE_FAILED` (nothing charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "504": { "description": "AI service timeout (`AI_SERVICE_TIMEOUT`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "507": { "description": "Media library full (`MEDIA_STORAGE_LIMIT_EXCEEDED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/carousels/{carousel_id}/edit": { "post": { "tags": [ "🎠 AI Carousels" ], "summary": "Edit a carousel", "description": "Applies one plain-language change to a finished carousel and answers with it, like generate. Only what the instruction targets is regenerated; slide order is kept, and every slide is saved again to the media library with the caption. A reword is free; a design change or a regenerated photo is charged as in AI chat. A different template is a new carousel (`EDIT_NEEDS_NEW_CAROUSEL`). An instruction that changes nothing is `EDIT_NOT_APPLIED`. A carousel can be edited for 7 days; after that, or from another workspace, it is `CAROUSEL_NOT_FOUND`.", "operationId": "editAiCarousel", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } }, { "name": "carousel_id", "in": "path", "description": "From the generate response", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "instruction" ], "properties": { "instruction": { "type": "string", "maxLength": 2000, "example": "Make the headline shorter" }, "slide": { "description": "1-based. Narrows the instruction to that slide.", "type": "integer", "minimum": 1, "example": 1, "nullable": true }, "language": { "type": "string", "nullable": true }, "use_brand": { "type": "boolean", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "The edited carousel, every slide newly saved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/CarouselDeck" } }, "type": "object" } } } }, "403": { "description": "Out of AI image credits (`IMAGE_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "404": { "description": "No carousel with this id in this workspace, or it is older than 7 days (`CAROUSEL_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "422": { "description": "`EDIT_NOT_APPLIED` or `EDIT_NEEDS_NEW_CAROUSEL`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "429": { "description": "`CAROUSEL_REQUESTS_LIMIT` or `RATE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "502": { "description": "Safe to retry: `CAROUSEL_GENERATION_FAILED`, `AI_SERVICE_UNAVAILABLE` or `MEDIA_PERSISTENCE_FAILED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } }, "504": { "description": "`AI_SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarouselError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/images/tools": { "get": { "tags": [ "🎨 AI Images" ], "summary": "List AI image tools", "description": "Live image-tool capabilities from the AI service, including each tool's JSON input schema. Video tools are not exposed.", "operationId": "listAiImageTools", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Tools retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "AI image tools retrieved successfully." }, "data": { "properties": { "tools": { "type": "array", "items": { "properties": { "key": { "type": "string", "example": "remove-background" }, "name": { "type": "string", "example": "Remove Background" }, "label": { "type": "string", "example": "Background Remover" }, "description": { "type": "string", "nullable": true }, "inputs": { "type": "array", "items": { "type": "object" } }, "controls": { "type": "array", "items": { "type": "object" } }, "supports_brand": { "type": "boolean", "example": false }, "input_schema": { "description": "JSON Schema for the public request body", "type": "object" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid" }, "403": { "description": "No access to this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`." }, "429": { "description": "Too many requests" } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/images/models": { "get": { "tags": [ "🎨 AI Images" ], "summary": "List available image models", "description": "Live image-model catalogue from the AI service with supported dimension presets.", "operationId": "listAiImageModels", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Models retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "AI image models retrieved successfully." }, "data": { "properties": { "models": { "type": "array", "items": { "properties": { "key": { "type": "string", "example": "nano-banana-pro" }, "supported_dimensions": { "type": "array", "items": { "type": "string" }, "example": [ "square", "portrait", "landscape", "story", "wide" ] }, "supported_resolutions": { "type": "array", "items": { "type": "string" } }, "supported_qualities": { "type": "array", "items": { "type": "string" } }, "default_dimension": { "type": "string", "nullable": true }, "supported_backgrounds": { "description": "Values `image_background` accepts for this model. Empty when the model ignores `image_background`.", "type": "array", "items": { "type": "string" }, "example": [ "auto", "opaque", "transparent" ] }, "credits_per_image": { "description": "Image credits charged per generated image: 1 for most models; 2 for gpt-image-1-mini; 3 for gpt-image-2.5-flare, nano-banana-2 and seedream-v5-pro; 5 for gpt-image-2, gpt-image-2.5-sunburst and nano-banana-pro; 6 for gpt-image-1.5. An edit adds a charge for its input images on the GPT image models, seedream-v5-pro (after the first) and flux_2; a flux_2_pro edit costs 4.", "type": "integer", "example": 3 }, "max_input_images": { "description": "Most source images (`image_urls`) the model accepts for editing. Null when the service does not report a limit.", "type": "integer", "example": 16, "nullable": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid" }, "403": { "description": "No access to this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`." }, "429": { "description": "Too many requests" } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/brand": { "get": { "tags": [ "🎨 AI Images" ], "summary": "Brand knowledge status", "description": "Reports whether the workspace has brand knowledge and whether it is enabled. Brand content is never returned.", "operationId": "getAiBrandStatus", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Brand status retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Brand status retrieved successfully." }, "data": { "properties": { "configured": { "type": "boolean", "example": true }, "enabled": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid" }, "403": { "description": "No access to this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`." }, "429": { "description": "Too many requests" } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/images/generate": { "post": { "tags": [ "🎨 AI Images" ], "summary": "Generate an image", "description": "Synchronously generates one image and saves it to the workspace content library. Supplying `image_url` or `image_urls` switches the request to image-to-image editing. Brand knowledge applies to both text and image transformations. The returned `media_id` is directly usable as `content.media.media_ids` when creating a post.", "operationId": "generateAiImage", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "maxLength": 10000, "example": "A flat-lay of autumn coffee beans on linen" }, "image_url": { "description": "Base image β€” switches the request to image-to-image. Must be publicly fetchable by the image service; an unreachable URL is `422 IMAGE_INPUT_REJECTED`.", "type": "string", "format": "url", "example": "https://example.com/your-image.png", "nullable": true }, "image_urls": { "description": "One or more source images for image-to-image transformation.", "type": "array", "items": { "type": "string", "format": "url" }, "minItems": 1, "nullable": true }, "model": { "description": "Must be one of the models returned by the models endpoint, e.g. `nano-banana` (the default when omitted), `nano-banana-pro`, `gpt-image-2`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`. Generation and editing (`image_url`) are both supported by every listed model. Cost per image: 1 credit for most models; 2 for `gpt-image-1-mini`; 3 for `gpt-image-2.5-flare`, `nano-banana-2` and `seedream-v5-pro`; 5 for `gpt-image-2`, `gpt-image-2.5-sunburst` and `nano-banana-pro`; 6 for `gpt-image-1.5`. An edit costs more on the models that bill input images: the GPT image models, `seedream-v5-pro` (after the first image) and `flux_2`; a `flux_2_pro` edit costs 4; the balance is checked against that cost before generating.", "type": "string", "example": "nano-banana-pro", "nullable": true }, "use_brand": { "description": "Overrides the stored workspace brand-enabled flag for this request. When omitted, the stored flag is honoured. No brand ID is accepted.", "type": "boolean", "nullable": true }, "dimensions": { "description": "Text-to-image output preset.", "type": "string", "enum": [ "square", "square_hd", "portrait", "portrait_4_5", "landscape", "landscape_16_9", "story", "wide" ], "example": "square_hd", "nullable": true }, "enhance_prompt": { "type": "boolean", "nullable": true }, "image_background": { "description": "Background of the generated image. Only honored by models that support it: gpt-image-2.5-flare, gpt-image-2.5-sunburst (see `supported_backgrounds` on the models endpoint); ignored by every other model. `transparent` returns a PNG with an alpha channel.", "type": "string", "enum": [ "auto", "opaque", "transparent" ], "example": "transparent", "nullable": true } }, "type": "object" }, "example": { "prompt": "A flat-lay of autumn coffee beans on linen", "dimensions": "square_hd" } } } }, "responses": { "200": { "description": "Image generated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Image generated." }, "data": { "properties": { "media_id": { "description": "The generated image, ready to pass to `POST /posts` as `content.media.media_ids`.", "type": "string", "example": "66f1a2b3c4d5e6f708192a3b", "nullable": true }, "url": { "type": "string", "example": "https://storage.googleapis.com/.../generated.png", "nullable": true }, "width": { "type": "integer", "example": 1024, "nullable": true }, "height": { "type": "integer", "example": 1024, "nullable": true }, "mime_type": { "type": "string", "example": "image/png", "nullable": true }, "model_used": { "type": "string", "example": "nano-banana-pro", "nullable": true }, "brand_applied": { "description": "Whether workspace brand knowledge was actually sent to generation.", "type": "boolean", "example": true }, "credits": { "properties": { "consumed": { "type": "integer", "example": 1 }, "available": { "description": "Image credits left afterwards. Null when the balance could not be read after the image was already generated and charged β€” never 0 as a stand-in.", "type": "integer", "example": 412, "nullable": true } }, "type": "object" }, "persist_error": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid" }, "403": { "description": "No workspace access, or image credits exhausted (`IMAGE_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`." }, "404": { "description": "`image_url` was supplied but the image-to-image tool is not available (`TOOL_NOT_FOUND`)" }, "422": { "description": "Validation error (`VALIDATION_ERROR`), content-policy refusal (`CONTENT_BLOCKED`), or inputs the image service would not work with β€” typically an image URL it could not fetch (`IMAGE_INPUT_REJECTED`)" }, "429": { "description": "Too many requests" }, "502": { "description": "AI service unavailable or retryable persistence failure (`AI_SERVICE_UNAVAILABLE`, `MEDIA_PERSISTENCE_FAILED`)" }, "507": { "description": "Workspace media storage limit exceeded (`MEDIA_STORAGE_LIMIT_EXCEEDED`)" }, "504": { "description": "AI service timeout (`AI_SERVICE_TIMEOUT`)" } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/images/tools/{tool_key}": { "post": { "tags": [ "🎨 AI Images" ], "summary": "Invoke an image tool", "description": "Synchronously runs one image tool, validates against its live input schema, and saves the result to the workspace content library. Prompt-driven tools can apply workspace brand knowledge.", "operationId": "invokeAiImageTool", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "tool_key", "in": "path", "description": "Tool key from the tools endpoint", "required": true, "schema": { "type": "string", "example": "remove-background" } } ], "requestBody": { "description": "Per-tool payload validated against `input_schema` from the discovery endpoint. `use_brand` is optional; no brand ID or brand content is accepted. Image URLs must be publicly fetchable by the image service.", "required": true, "content": { "application/json": { "schema": { "properties": { "image_url": { "type": "string", "format": "url", "example": "https://example.com/your-image.png" }, "prompt": { "description": "Required by prompt-driven tools such as image-to-image", "type": "string", "maxLength": 10000 }, "use_brand": { "description": "Overrides the stored workspace brand flag when this tool supports brand conditioning.", "type": "boolean", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Image generated." }, "data": { "properties": { "media_id": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true }, "mime_type": { "type": "string", "nullable": true }, "model_used": { "type": "string", "nullable": true }, "brand_applied": { "type": "boolean", "example": false }, "credits": { "properties": { "consumed": { "type": "integer", "example": 1 }, "available": { "type": "integer", "example": 411, "nullable": true } }, "type": "object" }, "persist_error": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid" }, "403": { "description": "No workspace access, or image credits exhausted (`IMAGE_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`." }, "404": { "description": "Unknown, disabled or video tool (`TOOL_NOT_FOUND`)" }, "422": { "description": "Validation error (`VALIDATION_ERROR`), content-policy refusal (`CONTENT_BLOCKED`), or inputs the image service would not work with β€” typically an image URL it could not fetch (`IMAGE_INPUT_REJECTED`)" }, "429": { "description": "Too many requests" }, "502": { "description": "AI service unavailable or retryable persistence failure (`AI_SERVICE_UNAVAILABLE`, `MEDIA_PERSISTENCE_FAILED`)" }, "507": { "description": "Workspace media storage limit exceeded (`MEDIA_STORAGE_LIMIT_EXCEEDED`)" }, "504": { "description": "AI service timeout (`AI_SERVICE_TIMEOUT`)" } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/jobs/{job_id}": { "get": { "tags": [ "🎬 AI Videos" ], "summary": "Get async video job status", "description": "Status of a video job the public API submitted. If `status` is `queued` or `processing`, call this same endpoint again after a short delay β€” there is no push notification, polling is the only way to learn when a job finishes. Terminal jobs (`completed`/`failed`/`cancelled`) are answered entirely from the local record and never need re-polling.", "operationId": "getAiJobStatus", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "job_id", "in": "path", "description": "Job ID returned by POST .../ai/videos/generate or POST .../ai/videos/tools/{tool_key}", "required": true, "schema": { "type": "string", "example": "wjob_abc123" } } ], "responses": { "200": { "description": "Job status retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Job status retrieved successfully. Poll this endpoint again if status is `queued` or `processing` β€” `completed`, `failed`, and `cancelled` are terminal." }, "data": { "properties": { "job_id": { "type": "string", "example": "wjob_abc123" }, "status": { "description": "`queued`/`processing`: not finished β€” poll this same endpoint again after a short delay, result and credits are not yet available. `completed`/`failed`/`cancelled`: terminal β€” no further polling needed, read `result` (if completed) and `credits` now.", "type": "string", "enum": [ "queued", "processing", "completed", "failed", "cancelled" ] }, "stage": { "description": "Raw upstream stage β€” informational, subject to change", "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "result": { "description": "Populated only when status is completed β€” contains the final video url, duration, resolution, and media_id. Null for every other status; do not treat a null result as a failure.", "type": "object", "nullable": true }, "estimated_credits": { "type": "integer", "nullable": true }, "credits": { "description": "Actual credits charged β€” null until terminal", "type": "integer", "nullable": true }, "brand_applied": { "type": "boolean", "nullable": true }, "error_code": { "description": "Stable machine-readable failure reason, populated only when status is failed and the upstream engine supplied one (e.g. `file_download_error`)", "type": "string", "nullable": true }, "error_message": { "description": "Clean, human-readable failure reason, populated only when status is failed", "type": "string", "nullable": true }, "error_details": { "description": "Structured diagnostic detail for the failure, populated only when status is failed", "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "No access to this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Job not found (`JOB_NOT_FOUND`) β€” never existed, or belongs to another workspace/source", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Job not found." }, "error_code": { "type": "string", "example": "JOB_NOT_FOUND" } }, "type": "object" } } } }, "422": { "description": "workspace_id in the body or query contradicts the path", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid input provided." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" } }, "type": "object" } } } }, "502": { "description": "AI service unavailable (`AI_SERVICE_UNAVAILABLE`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The AI video service is temporarily unavailable. Please try again." }, "error_code": { "type": "string", "example": "AI_SERVICE_UNAVAILABLE" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "🎬 AI Videos" ], "summary": "Cancel an async video job", "description": "Cancels a still-active job via the matching engine (Dramatiq or Temporal). Charges for partial work consumed on the Dramatiq path (PRD D8); reel/Temporal cancellation is currently free (Q15 unresolved).", "operationId": "cancelAiJob", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "job_id", "in": "path", "description": "Job ID returned by POST .../ai/videos/generate or POST .../ai/videos/tools/{tool_key}", "required": true, "schema": { "type": "string", "example": "wjob_abc123" } } ], "responses": { "200": { "description": "Job cancelled", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Job cancelled." }, "data": { "properties": { "job_id": { "type": "string", "example": "wjob_abc123" }, "status": { "type": "string", "example": "cancelled" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "No access to this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Job not found (`JOB_NOT_FOUND`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Job not found." }, "error_code": { "type": "string", "example": "JOB_NOT_FOUND" } }, "type": "object" } } } }, "409": { "description": "Job already terminal (`JOB_ALREADY_TERMINAL`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This job has already finished and cannot be cancelled." }, "error_code": { "type": "string", "example": "JOB_ALREADY_TERMINAL" } }, "type": "object" } } } }, "422": { "description": "workspace_id in the body or query contradicts the path", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid input provided." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" } }, "type": "object" } } } }, "502": { "description": "AI service unavailable (`AI_SERVICE_UNAVAILABLE`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The AI video service is temporarily unavailable. Please try again." }, "error_code": { "type": "string", "example": "AI_SERVICE_UNAVAILABLE" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/jobs": { "get": { "tags": [ "🎬 AI Videos" ], "summary": "List async video jobs", "description": "Video jobs the public API itself submitted for this workspace β€” never jobs originated by chat or internal tools, even though they share the same underlying record. Local snapshot only, no live upstream poll per row β€” a row's status can lag a few seconds behind reality. To force a fresh check on one specific job, call GET .../ai/jobs/{job_id} instead.", "operationId": "listAiJobs", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "cancelled" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100 } } ], "responses": { "200": { "description": "Jobs retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Jobs retrieved successfully. Call GET .../ai/jobs/{job_id} to get live status for one job." }, "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "No access to this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "Validation error (`VALIDATION_ERROR`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid input provided." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/videos/tools": { "get": { "tags": [ "🎬 AI Videos" ], "summary": "List AI video tools", "description": "Enabled video tools with their input descriptors, duration limits and cost. Image tools are not exposed.", "operationId": "listAiVideoTools", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Tools retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "AI video tools retrieved successfully. Use the returned `key` as the `{tool_key}` path segment when calling POST .../ai/videos/tools/{tool_key}." }, "tools": { "type": "array", "items": { "properties": { "key": { "description": "Use this as the `{tool_key}` path segment in POST .../ai/videos/tools/{tool_key} to invoke this tool.", "type": "string", "example": "motion-control" }, "label": { "type": "string", "example": "Motion Control" }, "description": { "type": "string", "nullable": true }, "inputs": { "type": "array", "items": { "type": "object" }, "example": [ { "name": "image_url", "required": true, "kind": "image_url" }, { "name": "video_url", "required": true, "kind": "video_url" } ] }, "duration": { "properties": { "min_seconds": { "type": "integer", "example": 1 }, "max_seconds": { "type": "integer", "example": 30 } }, "type": "object", "nullable": true }, "cost": { "properties": { "type": { "type": "string", "example": "per_second" }, "credits_per_second": { "type": "number", "example": 5.04 } }, "type": "object", "nullable": true }, "accepts_audio": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "No access to this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "workspace_id in the body or query contradicts the path", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid input provided." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/videos/models": { "get": { "tags": [ "🎬 AI Videos" ], "summary": "List available video models", "description": "Every model the generate endpoint can select, with modes/resolutions/durations. Live registry, not a curated subset.", "operationId": "listAiVideoModels", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Models retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "AI video models retrieved successfully. Use the returned `key` as `model` when calling POST .../ai/videos/generate or GET .../ai/videos/estimate." }, "models": { "type": "array", "items": { "properties": { "key": { "description": "Use this as `model` in POST .../ai/videos/generate or GET .../ai/videos/estimate.", "type": "string", "example": "wan-2.7" }, "modes": { "type": "array", "items": { "type": "string" }, "example": [ "text-to-video", "image-to-video", "reference-to-video" ] }, "supported_resolutions": { "type": "array", "items": { "type": "string" }, "example": [ "720p", "1080p" ] }, "duration": { "description": "Bounds of the model's valid duration range, in seconds. Always present alongside supported_durations when the set is not every integer in between.", "properties": { "min_seconds": { "type": "integer", "example": 2 }, "max_seconds": { "type": "integer", "example": 15 } }, "type": "object", "nullable": true }, "supported_durations": { "description": "Present only when the valid durations are NOT every integer between duration.min_seconds and max_seconds β€” the exact allowed set (e.g. [5, 10, 15]).", "type": "array", "items": { "type": "integer" }, "example": [ 5, 10, 15 ], "nullable": true }, "supported_ratios": { "type": "array", "items": { "type": "string" }, "example": [ "16:9", "9:16", "1:1" ] }, "supports_audio": { "type": "boolean" }, "default_duration": { "type": "integer", "example": 5, "nullable": true }, "default_resolution": { "type": "string", "example": "1080p", "nullable": true }, "default_aspect_ratio": { "type": "string", "example": "16:9", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "No access to this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "workspace_id in the body or query contradicts the path", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid input provided." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/videos/estimate": { "get": { "tags": [ "🎬 AI Videos" ], "summary": "Estimate video generation cost", "description": "Real, model-priced credit cost and processing-time estimate for a generate() request. Nothing is submitted or charged β€” a read-only calculation, hence GET. To actually submit the job with the same parameters, call POST .../ai/videos/generate; the credits reported here are deducted only when that job completes, not by this call.", "operationId": "estimateAiVideoCost", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "duration_seconds", "in": "query", "required": false, "schema": { "type": "number", "example": 4 } }, { "name": "model", "in": "query", "description": "Must be one of the models returned by the models endpoint", "required": false, "schema": { "type": "string", "example": "wan-2.7", "nullable": true } }, { "name": "resolution", "in": "query", "required": false, "schema": { "type": "string", "example": "720p", "nullable": true } }, { "name": "generation_mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "text-to-video", "image-to-video", "reference-to-video" ], "example": "text-to-video" } }, { "name": "enable_audio", "in": "query", "required": false, "schema": { "type": "boolean", "nullable": true } }, { "name": "aspect_ratio", "in": "query", "required": false, "schema": { "type": "string", "example": "16:9", "nullable": true } }, { "name": "enhance_prompt", "in": "query", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "responses": { "200": { "description": "Estimate computed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Video cost estimated. Nothing was submitted or charged β€” call POST .../ai/videos/generate with the same parameters to submit the job." }, "data": { "properties": { "credits": { "type": "integer", "example": 3 }, "estimated_seconds": { "type": "integer", "example": 34 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "No access to this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "Validation error (`VALIDATION_ERROR`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid input provided." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" } }, "type": "object" } } } }, "502": { "description": "AI service unavailable (`AI_SERVICE_UNAVAILABLE`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The AI video service is temporarily unavailable. Please try again." }, "error_code": { "type": "string", "example": "AI_SERVICE_UNAVAILABLE" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/videos/generate": { "post": { "tags": [ "🎬 AI Videos" ], "summary": "Submit a video generation job", "description": "Asynchronously submits text-to-video, image-to-video, or reference-to-video generation and returns a job handle immediately β€” the video is not ready yet. Use the returned `job_id` (or `status_url`) with GET .../ai/jobs/{job_id} to poll until status is completed, failed, or cancelled.", "operationId": "generateAiVideo", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "maxLength": 10000, "example": "A drone shot flying over autumn coffee fields" }, "image_url": { "description": "Switches to image-to-video. Mutually exclusive with reference_image_urls.", "type": "string", "format": "url", "nullable": true }, "reference_image_urls": { "description": "Switches to reference-to-video. Mutually exclusive with image_url.", "type": "array", "items": { "type": "string" }, "nullable": true }, "model": { "description": "Must be one of the models returned by the models endpoint", "type": "string", "nullable": true }, "duration_seconds": { "type": "number", "nullable": true }, "resolution": { "type": "string", "nullable": true }, "aspect_ratio": { "type": "string", "nullable": true }, "enable_audio": { "type": "boolean", "nullable": true }, "enhance_prompt": { "type": "boolean", "nullable": true }, "style": { "type": "string", "nullable": true }, "use_brand": { "description": "Apply the workspace's brand knowledge. No brand ID accepted β€” resolved server-side.", "type": "boolean", "default": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Job submitted", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Video generation submitted. Use the returned `job_id` with GET .../ai/jobs/{job_id} to poll for the result." }, "data": { "properties": { "job_id": { "description": "Use this as `{job_id}` in GET/DELETE .../ai/jobs/{job_id} to poll status or cancel.", "type": "string", "example": "wjob_abc123" }, "status_url": { "description": "The exact GET URL to poll for this job's status β€” equivalent to building it yourself from job_id.", "type": "string", "example": "/api/v1/workspaces/610a1e660cb41530ca40d372/ai/jobs/wjob_abc123" }, "status": { "description": "The job has not finished yet. Poll status_url until it reports completed, failed, or cancelled β€” this response's result fields (video url, etc.) are not available yet.", "type": "string", "example": "queued" }, "estimated_credits": { "type": "integer", "example": 3 }, "estimated_seconds": { "type": "integer", "example": 34, "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "No workspace access, insufficient video credits (`INSUFFICIENT_VIDEO_CREDITS`), or storage full (`STORAGE_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Not enough ai video credits." }, "error_code": { "description": "Absent for a plain workspace-access denial", "type": "string", "example": "INSUFFICIENT_VIDEO_CREDITS", "nullable": true } }, "type": "object" } } } }, "422": { "description": "Validation error (`VALIDATION_ERROR`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid input provided." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" } }, "type": "object" } } } }, "502": { "description": "AI service unavailable (`AI_SERVICE_UNAVAILABLE`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The AI video service is temporarily unavailable. Please try again." }, "error_code": { "type": "string", "example": "AI_SERVICE_UNAVAILABLE" } }, "type": "object" } } } }, "504": { "description": "AI service timeout (`AI_SERVICE_TIMEOUT`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The AI video service timed out. Please try again." }, "error_code": { "type": "string", "example": "AI_SERVICE_TIMEOUT" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/ai/videos/tools/{tool_key}": { "post": { "tags": [ "🎬 AI Videos" ], "summary": "Invoke a dedicated video tool", "description": "Submits motion-control, lip-sync, or talking-avatar and returns a job handle immediately β€” the video is not ready yet. Use the returned `job_id` (or `status_url`) with GET .../ai/jobs/{job_id} to poll until status is completed, failed, or cancelled.", "operationId": "invokeAiVideoTool", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "tool_key", "in": "path", "description": "One of the video tool keys returned by GET .../ai/videos/tools", "required": true, "schema": { "type": "string", "example": "motion-control" } } ], "requestBody": { "description": "Fields vary per tool_key β€” see GET .../ai/videos/tools for each tool's input descriptor. E.g. motion-control: image_url, video_url; lip-sync: video_url, audio_url; talking-avatar: image_url, audio_url.", "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Job submitted", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Video tool submitted. Use the returned `job_id` with GET .../ai/jobs/{job_id} to poll for the result." }, "data": { "properties": { "job_id": { "description": "Use this as `{job_id}` in GET/DELETE .../ai/jobs/{job_id} to poll status or cancel.", "type": "string", "example": "wjob_abc123" }, "status_url": { "description": "The exact GET URL to poll for this job's status β€” equivalent to building it yourself from job_id.", "type": "string", "example": "/api/v1/workspaces/610a1e660cb41530ca40d372/ai/jobs/wjob_abc123" }, "status": { "description": "The job has not finished yet. Poll status_url until it reports completed, failed, or cancelled β€” this response's result fields (video url, etc.) are not available yet.", "type": "string", "example": "queued" }, "estimated_credits": { "description": "Null only when the tool's capability feed has no published per-second cost", "type": "integer", "example": 36, "nullable": true }, "estimated_seconds": { "type": "integer", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "No workspace access, or insufficient video credits (`INSUFFICIENT_VIDEO_CREDITS`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Not enough ai video credits." }, "error_code": { "description": "Absent for a plain workspace-access denial", "type": "string", "example": "INSUFFICIENT_VIDEO_CREDITS", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Unknown, disabled, or non-video tool_key (`TOOL_NOT_FOUND`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This tool is not available." }, "error_code": { "type": "string", "example": "TOOL_NOT_FOUND" } }, "type": "object" } } } }, "422": { "description": "Validation error (`VALIDATION_ERROR`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid input provided." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" } }, "type": "object" } } } }, "502": { "description": "AI service unavailable (`AI_SERVICE_UNAVAILABLE`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The AI video service is temporarily unavailable. Please try again." }, "error_code": { "type": "string", "example": "AI_SERVICE_UNAVAILABLE" } }, "type": "object" } } } }, "504": { "description": "AI service timeout (`AI_SERVICE_TIMEOUT`)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The AI video service timed out. Please try again." }, "error_code": { "type": "string", "example": "AI_SERVICE_TIMEOUT" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/accounts/{platform_id}/preferences": { "get": { "tags": [ "βš™οΈ Account Preferences" ], "summary": "Read an account's analytics preferences", "description": "Returns the stored preferences for a connected account. Only YouTube accounts carry any: analytics_data_deleted and last_youtube_consent_time. An account with none returns an empty object, which means 'nothing set', not 'account not found' - that is a 404.", "operationId": "getAccountAnalyticsPreferences", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "platform_id", "in": "path", "description": "The account's identifier on the platform.", "required": true, "schema": { "type": "string", "example": "UCiOAv7TKR2Y0Ja-dGAWMNyw" } } ], "responses": { "200": { "description": "The account's preferences", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "platform_id": { "type": "string" }, "platform_type": { "type": "string", "example": "youtube" }, "preferences": { "type": "object", "example": { "analytics_data_deleted": false } } }, "type": "object" } } } }, "404": { "description": "No such account in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "βš™οΈ Account Preferences" ], "summary": "Set one analytics preference on an account", "description": "Sets a single key. Only YouTube accounts have preferences, and only two keys exist - both about YouTube data-handling consent, not report appearance. To change what a report contains, pass `sections` when generating it or on its schedule.", "operationId": "setAccountAnalyticsPreference", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "platform_id", "in": "path", "required": true, "schema": { "type": "string", "example": "UCiOAv7TKR2Y0Ja-dGAWMNyw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "platform", "key", "value" ], "properties": { "platform": { "type": "string", "enum": [ "youtube" ] }, "key": { "type": "string", "enum": [ "analytics_data_deleted", "last_youtube_consent_time" ] }, "value": { "description": "A flag for analytics_data_deleted, a timestamp for last_youtube_consent_time." } }, "type": "object" }, "example": { "platform": "youtube", "key": "last_youtube_consent_time", "value": "2026-03-01T09:00:00Z" } } } }, "responses": { "200": { "description": "Preference set; the response carries the account's preferences after the change.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such account in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/bluesky/summary": { "get": { "tags": [ "πŸ“Š Analytics: Bluesky" ], "summary": "Bluesky summary KPIs β€” current vs previous period", "description": "Authored-post totals for the period plus the current profile counters. Note the absent metrics: there is no impressions, reach or click figure because the AT Protocol publishes none. `engagement_rate` is normalised by follower count, NOT impressions, so it is not comparable to the Facebook or LinkedIn engagement rate. `bookmarks` is null when no post in the period reported a bookmark count β€” that is 'unknown', not zero.", "operationId": "blueskyAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Metrics broken into `current`, `previous`, absolute `difference` and `percentage` change.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "total_posts": 42, "likes": 1820, "reposts": 240, "replies": 310, "quotes": 55, "post_engagement": 2425, "engagement_rate": 0.41, "followers": 595137, "following": 3974, "profile_posts_all_time": 4110, "bookmarks": 190, "bookmarks_partial": false }, "previous": { "total_posts": 38, "likes": 1610, "reposts": 205, "replies": 280, "quotes": 44, "post_engagement": 2139, "engagement_rate": 0.37, "followers": 588400, "following": 3960, "profile_posts_all_time": 4068, "bookmarks": 170, "bookmarks_partial": false } } }, "capabilities": { "description": "Which sections this platform can answer, and the reason for each unavailable metric.", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/bluesky/audience-growth": { "get": { "tags": [ "πŸ“Š Analytics: Bluesky" ], "summary": "Bluesky follower trend, tracked since connection", "description": "Daily follower totals assembled from the snapshots ContentStudio retained. Bluesky exposes no historical follower data, so days before the first sync carry `tracked: false` and hold no value β€” they must be rendered as 'not tracked', never as zero followers. `capabilities.tracking.tracked_since` gives the first day with data.", "operationId": "blueskyAnalyticsAudienceGrowth", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Follower trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "audience_growth": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-08-18" }, "followers_count": { "type": "integer", "example": 595137 }, "followers_daily": { "type": "integer", "example": 412 }, "following_count": { "type": "integer", "example": 3974 }, "tracked": { "description": "False for days before the first retained snapshot.", "type": "boolean", "example": true } }, "type": "object" } }, "audience_growth_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object" }, "capabilities": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/bluesky/engagement": { "get": { "tags": [ "πŸ“Š Analytics: Bluesky" ], "summary": "Bluesky engagement trend by post publish date", "description": "Engagement earned by the posts PUBLISHED on each day, measured at the last sync β€” not engagement that occurred on that day. Bluesky post counters are cumulative lifetime values and the protocol offers no per-interval metric, so a true daily interaction curve is not derivable. Accepts an optional comma-separated `media_type` filter (text, image, gallery, video, link, record, other).", "operationId": "blueskyAnalyticsEngagement", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "description": "Comma-separated media types to include.", "required": false, "schema": { "type": "string", "example": "image,gallery,video" } } ], "responses": { "200": { "description": "Engagement trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "engagement": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-08-18" }, "likes": { "type": "integer", "example": 124 }, "reposts": { "type": "integer", "example": 13 }, "replies": { "type": "integer", "example": 18 }, "quotes": { "type": "integer", "example": 1 }, "total_posts": { "type": "integer", "example": 2 }, "engagement": { "type": "integer", "example": 156 }, "engagement_rate": { "type": "number", "format": "float", "example": 0.03 } }, "type": "object" } }, "engagement_rollup": { "type": "object" }, "capabilities": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/bluesky/publishing-behaviour": { "get": { "tags": [ "πŸ“Š Analytics: Bluesky" ], "summary": "Bluesky publishing behaviour with a per-media-type rollup", "description": "Posting volume and engagement over time, plus a rollup broken down by media type (text, image, gallery, video, link, record, other) with a `total` row. Reposts by the account are excluded throughout β€” only authored posts are counted.", "operationId": "blueskyAnalyticsPublishingBehaviour", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "description": "Comma-separated media types to include in the time series.", "required": false, "schema": { "type": "string", "example": "image,video" } } ], "responses": { "200": { "description": "Publishing behaviour retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "publishing_behaviour": { "type": "array", "items": { "type": "object" } }, "publishing_behaviour_rollup": { "properties": { "current": { "type": "array", "items": { "type": "object" } }, "previous": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "capabilities": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/bluesky/top-posts": { "get": { "tags": [ "πŸ“Š Analytics: Bluesky" ], "summary": "Bluesky top authored posts (default 3)", "description": "Highest-performing authored posts. `order_by` accepts engagement, engagement_rate, likes, reposts, replies, quotes, bookmarks or published_at β€” there is deliberately no reach or impressions option, because no such measurement exists; an unrecognised value falls back to engagement rather than fabricating an order. `bookmark_count` may be null, meaning the value was not reported.", "operationId": "blueskyAnalyticsTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "example": 3 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "example": 0 } }, { "name": "order_by", "in": "query", "description": "Sort metric.", "required": false, "schema": { "type": "string", "enum": [ "engagement", "post_engagement", "total_engagement", "engagement_rate", "likes", "like_count", "reposts", "repost_count", "shares", "replies", "reply_count", "comments", "quotes", "quote_count", "bookmarks", "bookmark_count", "published_at", "created_at", "caption", "text" ], "example": "engagement" } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "media_type", "in": "query", "required": false, "schema": { "type": "string", "example": "image,gallery" } }, { "name": "hashtags", "in": "query", "description": "Comma-separated hashtags, matched case-insensitively.", "required": false, "schema": { "type": "string", "example": "atmosphereconf" } } ], "responses": { "200": { "description": "Top posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "properties": { "post_id": { "type": "string", "example": "3mrstdqk67k2a" }, "uri": { "type": "string", "example": "at://did:plc:oky5czdrnfjpqslsw2a5iclo/app.bsky.feed.post/3mrstdqk67k2a" }, "permalink": { "type": "string", "example": "https://bsky.app/profile/jay.bsky.team/post/3mrstdqk67k2a" }, "media_type": { "type": "string", "example": "gallery" }, "like_count": { "type": "integer", "example": 124 }, "share_count": { "description": "Bluesky reposts.", "type": "integer", "example": 13 }, "reply_count": { "type": "integer", "example": 18 }, "quote_count": { "type": "integer", "example": 1 }, "bookmark_count": { "type": "integer", "example": 1, "nullable": true }, "post_engagement": { "type": "integer", "example": 156 }, "last_synced_at": { "description": "When these cumulative counters were read.", "type": "string", "example": "2026-08-18T07:23:45Z" } }, "type": "object" } }, "capabilities": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/bluesky/sorted-top-posts": { "get": { "tags": [ "πŸ“Š Analytics: Bluesky" ], "summary": "Bluesky paginated post table (default 15)", "description": "Same payload and sort options as top-posts with a larger default page size, for the sortable posts table.", "operationId": "blueskyAnalyticsSortedTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "example": 15 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "example": 0 } }, { "name": "order_by", "in": "query", "description": "Sort field. caption sorts the post text alphabetically; anything else falls back to engagement.", "required": false, "schema": { "type": "string", "default": "engagement", "enum": [ "engagement", "post_engagement", "total_engagement", "engagement_rate", "likes", "like_count", "reposts", "repost_count", "shares", "replies", "reply_count", "comments", "quotes", "quote_count", "bookmarks", "bookmark_count", "published_at", "created_at", "caption", "text" ], "example": "likes" } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "media_type", "in": "query", "required": false, "schema": { "type": "string", "example": "video" } }, { "name": "hashtags", "in": "query", "required": false, "schema": { "type": "string", "example": "photography" } } ], "responses": { "200": { "description": "Post table retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "type": "object" } }, "capabilities": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/bluesky/post": { "get": { "tags": [ "πŸ“Š Analytics: Bluesky" ], "summary": "Bluesky single post detail", "description": "One authored post by its record key (rkey β€” the last segment of the at:// uri). The lookup is by identity and the date window never filters the result, so a post older than the dashboard range is still retrievable. The window is REQUIRED nonetheless β€” upstream validates it before it reads `post_id` β€” so it must be sent rather than omitted.", "operationId": "blueskyAnalyticsSinglePost", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "post_id", "in": "query", "description": "The post record key (rkey).", "required": true, "schema": { "type": "string", "example": "3mrstdqk67k2a" } } ], "responses": { "200": { "description": "Post retrieved successfully. `post` is null when no such post is stored for this account.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "post": { "description": "Same shape as a /top-posts item.", "properties": { "published_at": { "description": "Publish time in the requested `timezone` (RFC 3339 with its offset); null when unknown.", "type": "string", "format": "date-time", "example": "2026-01-22T09:08:00-05:00", "nullable": true } }, "type": "object", "nullable": true }, "capabilities": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/bluesky/posts-per-days": { "get": { "tags": [ "πŸ“Š Analytics: Bluesky" ], "summary": "Bluesky posting cadence by weekday", "description": "How many posts were published on each weekday. The weekday is computed from the publish time in the requested timezone, so a workspace outside UTC sees its own days.", "operationId": "blueskyAnalyticsPostsPerDays", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Posting cadence retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "posts_per_days": { "properties": { "data": { "properties": { "days": { "type": "object", "example": { "Monday": 6, "Tuesday": 4, "Wednesday": 7, "Thursday": 5, "Friday": 8, "Saturday": 1, "Sunday": 2 } }, "show_data": { "type": "integer", "example": 33 } }, "type": "object" } }, "type": "object" }, "capabilities": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/bluesky/hashtags": { "get": { "tags": [ "πŸ“Š Analytics: Bluesky" ], "summary": "Bluesky top hashtags by engagement", "description": "Top hashtags from richtext tag facets and the record's explicit tags. Tags are stored and returned lowercase so one tag aggregates into one row instead of splitting across casings. Bluesky publishes no hashtag reach or search-volume metric, so these are usage and engagement figures only.", "operationId": "blueskyAnalyticsHashtags", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Hashtags retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_hashtags": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "atmosphereconf" }, "engagements": { "type": "integer", "example": 420 }, "likes": { "type": "integer", "example": 310 }, "reposts": { "type": "integer", "example": 54 }, "replies": { "type": "integer", "example": 48 }, "quotes": { "type": "integer", "example": 8 }, "posts": { "type": "integer", "example": 6 } }, "type": "object" } }, "top_hashtags_rollup": { "type": "object" }, "capabilities": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/bluesky/capabilities": { "get": { "tags": [ "πŸ“Š Analytics: Bluesky" ], "summary": "Which Bluesky metrics are available, and why the rest are not", "description": "Machine-readable statement of what this platform can answer. Consumers should read `unavailable` rather than hardcoding the gaps, and must render those metrics as unavailable β€” not as zero. `tracking.tracked_since` is the first day a follower snapshot was retained; nothing before it exists or can be backfilled.", "operationId": "blueskyAnalyticsCapabilities", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Capabilities retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "capabilities": { "properties": { "available": { "type": "array", "items": { "type": "string" }, "example": [ "summary", "audienceGrowth", "engagement", "publishingBehaviour", "topPosts", "sortedTopPosts", "post", "postsPerDays", "hashtags" ] }, "unavailable": { "type": "array", "items": { "properties": { "metric": { "type": "string", "example": "impressions" }, "reason": { "type": "string", "example": "The AT Protocol exposes no impression count at post or account level." } }, "type": "object" } }, "notes": { "type": "array", "items": { "type": "string" } }, "tracking": { "properties": { "tracked_since": { "type": "string", "example": "2026-08-01" }, "snapshot_days": { "type": "integer", "example": 18 }, "trends_start_at_connection": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/campaigns-labels/summary": { "post": { "tags": [ "πŸ—‚οΈ Campaigns & Labels" ], "summary": "Campaign & label summary KPIs β€” current vs previous period", "description": "`total_engagement_rate_per_impression` and the per-post `engagement_rate` are percentages (engagement / impressions * 100) on every platform.", "operationId": "campaignLabelAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignLabelScopeBody" } } } }, "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Broken into `current`, `previous`, absolute `difference` and `percentage` change. Each block carries the same metric keys.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "total_posts": 115, "total_engagement": 48210, "total_impressions": 2546042, "total_engagement_rate_per_impression": 1.89, "total_reach": 1507736, "total_video_views": 812430, "total_link_clicks": 9184 }, "previous": { "total_posts": 98, "total_engagement": 41065, "total_impressions": 2183900, "total_engagement_rate_per_impression": 1.88, "total_reach": 1322480, "total_video_views": 702118, "total_link_clicks": 8021 }, "difference": { "total_posts": 17, "total_engagement": 7145, "total_impressions": 362142, "total_engagement_rate_per_impression": 0.01, "total_reach": 185256, "total_video_views": 110312, "total_link_clicks": 1163 }, "percentage": { "total_posts": 17.3, "total_engagement": 17.4, "total_impressions": 16.6, "total_engagement_rate_per_impression": 0.5, "total_reach": 14, "total_video_views": 15.7, "total_link_clicks": 14.5 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to workspace" } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found" } }, "type": "object" } } } }, "422": { "description": "Validation failed, or a campaign/label outside this workspace", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "description": "Field-level validation errors. Absent on a scope rejection.", "properties": { "start_date": { "type": "array", "items": { "type": "string", "example": "The start date field is required." } } }, "type": "object" }, "error_code": { "description": "Present only when an id does not belong to the workspace.", "type": "string", "example": "CAMPAIGN_LABEL_OUT_OF_SCOPE" }, "campaigns": { "description": "The rejected campaign IDs.", "type": "array", "items": { "type": "string" }, "example": [ "64f0a1b2c3d4e5f60718293a" ] }, "labels": { "description": "The rejected label IDs.", "type": "array", "items": { "type": "string" }, "example": [] } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests" }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "We couldn't load your analytics right now. Please try again." }, "error_code": { "type": "string", "example": "ANALYTICS_UPSTREAM_ERROR" }, "upstream_status": { "type": "integer", "example": 503 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/campaigns-labels/breakdown": { "post": { "tags": [ "πŸ—‚οΈ Campaigns & Labels" ], "summary": "Per-campaign and per-label totals, current vs previous period", "description": "Splits the same scope as the summary endpoint into one row per campaign and one per label, so each can be compared against the others and against its own previous period. Only the three metrics every network reports are broken down: posts, engagement and impressions.", "operationId": "campaignLabelAnalyticsBreakdown", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignLabelScopeBody" } } } }, "responses": { "200": { "description": "Breakdown retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignLabelBreakdownEntity" } }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignLabelBreakdownEntity" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to workspace" } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found" } }, "type": "object" } } } }, "422": { "description": "Validation failed, or a campaign/label outside this workspace", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "description": "Field-level validation errors. Absent on a scope rejection.", "properties": { "start_date": { "type": "array", "items": { "type": "string", "example": "The start date field is required." } } }, "type": "object" }, "error_code": { "description": "Present only when an id does not belong to the workspace.", "type": "string", "example": "CAMPAIGN_LABEL_OUT_OF_SCOPE" }, "campaigns": { "description": "The rejected campaign IDs.", "type": "array", "items": { "type": "string" }, "example": [ "64f0a1b2c3d4e5f60718293a" ] }, "labels": { "description": "The rejected label IDs.", "type": "array", "items": { "type": "string" }, "example": [] } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests" }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "We couldn't load your analytics right now. Please try again." }, "error_code": { "type": "string", "example": "ANALYTICS_UPSTREAM_ERROR" }, "upstream_status": { "type": "integer", "example": 503 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/campaigns-labels/insights-breakdown": { "post": { "tags": [ "πŸ—‚οΈ Campaigns & Labels" ], "summary": "Daily time series per campaign and per label", "description": "The same three universally-reported metrics as the breakdown endpoint, but as a daily series rather than a period total β€” this is what backs the trend graphs. Every selected campaign and label is present as a key; points run oldest to newest and days with no posts are zero-filled, so series from different entities stay index-aligned.", "operationId": "campaignLabelAnalyticsInsightsBreakdown", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignLabelScopeBody" } } } }, "responses": { "200": { "description": "Insights breakdown retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "campaigns": { "description": "Keyed by campaign ID; each value is that campaign's daily series.", "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignLabelInsightsPoint" } } }, "labels": { "description": "Keyed by label ID; each value is that label's daily series.", "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignLabelInsightsPoint" } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to workspace" } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found" } }, "type": "object" } } } }, "422": { "description": "Validation failed, or a campaign/label outside this workspace", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "description": "Field-level validation errors. Absent on a scope rejection.", "properties": { "start_date": { "type": "array", "items": { "type": "string", "example": "The start date field is required." } } }, "type": "object" }, "error_code": { "description": "Present only when an id does not belong to the workspace.", "type": "string", "example": "CAMPAIGN_LABEL_OUT_OF_SCOPE" }, "campaigns": { "description": "The rejected campaign IDs.", "type": "array", "items": { "type": "string" }, "example": [ "64f0a1b2c3d4e5f60718293a" ] }, "labels": { "description": "The rejected label IDs.", "type": "array", "items": { "type": "string" }, "example": [] } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests" }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "We couldn't load your analytics right now. Please try again." }, "error_code": { "type": "string", "example": "ANALYTICS_UPSTREAM_ERROR" }, "upstream_status": { "type": "integer", "example": 503 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/campaigns-labels/posts": { "post": { "tags": [ "πŸ—‚οΈ Campaigns & Labels" ], "summary": "Per-post table for the selected campaigns & labels", "description": "The top `limit` posts overall (or within `platforms`), server-sorted. Metrics are literal: a network that does not report one returns `null`, which sorts last in both directions. `impressions` and `reach` carry the same substitutions as the summary KPIs so the columns reconcile with the cards β€” Instagram/YouTube `impressions` read `views`, TikTok reads `view_count` for both. Use this endpoint to tabulate, never to rank.", "operationId": "campaignLabelAnalyticsPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignLabelPostsBody" } } } }, "responses": { "200": { "description": "Posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignLabelPostRow" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to workspace" } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found" } }, "type": "object" } } } }, "422": { "description": "Validation failed, or a campaign/label outside this workspace", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "description": "Field-level validation errors. Absent on a scope rejection.", "properties": { "start_date": { "type": "array", "items": { "type": "string", "example": "The start date field is required." } } }, "type": "object" }, "error_code": { "description": "Present only when an id does not belong to the workspace.", "type": "string", "example": "CAMPAIGN_LABEL_OUT_OF_SCOPE" }, "campaigns": { "description": "The rejected campaign IDs.", "type": "array", "items": { "type": "string" }, "example": [ "64f0a1b2c3d4e5f60718293a" ] }, "labels": { "description": "The rejected label IDs.", "type": "array", "items": { "type": "string" }, "example": [] } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests" }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "We couldn't load your analytics right now. Please try again." }, "error_code": { "type": "string", "example": "ANALYTICS_UPSTREAM_ERROR" }, "upstream_status": { "type": "integer", "example": 503 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/campaigns-labels/top-posts": { "post": { "tags": [ "πŸ—‚οΈ Campaigns & Labels" ], "summary": "Top 5 posts per network for the selected campaigns & labels", "description": "Same payload and response as the posts endpoint, except `limit` is ignored: this always returns 5 posts per selected network, merged and globally ordered by `sort_by`. Unlike the posts endpoint, `impressions` and `reach` are filled on networks that do not report them (TikTok ← view count; YouTube reach ← views; Pinterest reach ← impressions) so `engagement`, `impressions` and `reach` are rankable everywhere and no network comes back empty for lack of the metric. The substituted value is what the response returns, so the two endpoints can legitimately report different `impressions`/`reach` for the same post despite the identical envelope. Use this endpoint to rank, never to tabulate.", "operationId": "campaignLabelAnalyticsTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignLabelPostsBody" } } } }, "responses": { "200": { "description": "Top posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignLabelPostRow" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to workspace" } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found" } }, "type": "object" } } } }, "422": { "description": "Validation failed, or a campaign/label outside this workspace", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "description": "Field-level validation errors. Absent on a scope rejection.", "properties": { "start_date": { "type": "array", "items": { "type": "string", "example": "The start date field is required." } } }, "type": "object" }, "error_code": { "description": "Present only when an id does not belong to the workspace.", "type": "string", "example": "CAMPAIGN_LABEL_OUT_OF_SCOPE" }, "campaigns": { "description": "The rejected campaign IDs.", "type": "array", "items": { "type": "string" }, "example": [ "64f0a1b2c3d4e5f60718293a" ] }, "labels": { "description": "The rejected label IDs.", "type": "array", "items": { "type": "string" }, "example": [] } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests" }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "We couldn't load your analytics right now. Please try again." }, "error_code": { "type": "string", "example": "ANALYTICS_UPSTREAM_ERROR" }, "upstream_status": { "type": "integer", "example": 503 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/competitor-reports": { "get": { "tags": [ "πŸ“Š Competitor Reports" ], "summary": "List a workspace's saved competitor reports", "operationId": "listCompetitorReports", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "platforms", "in": "query", "description": "Comma-separated platform filter. OMIT IT to get every report in the workspace; an empty value is not a filter matching nothing.", "required": false, "schema": { "type": "string", "example": "facebook,instagram" } } ], "responses": { "200": { "description": "Reports retrieved. An empty `competitor_reports` array means the workspace has no reports matching the filter - it does not mean the workspace is unknown, which is a 403.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "competitor_reports": { "type": "array", "items": { "properties": { "id": { "description": "Pass as competitor_report_id to the competitor analytics endpoints", "type": "string" }, "name": { "type": "string" }, "platform_type": { "type": "string", "example": "facebook" }, "created_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true }, "competitors": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "competitor_id": { "description": "The competitor's id on the platform", "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "image": { "type": "string", "nullable": true }, "state": { "$ref": "#/components/schemas/CompetitorState" }, "is_active": { "type": "boolean", "nullable": true } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“Š Competitor Reports" ], "summary": "Create a saved competitor report", "description": "There is no maximum number of competitors per report, and competitors are not metered individually. Like every public API call, this request spends one api_credit; a provisioning flow that searches for each competitor before creating the report spends one per search as well.", "operationId": "createCompetitorReport", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "platform_type", "competitors" ], "properties": { "name": { "type": "string", "example": "Key rivals" }, "platform_type": { "type": "string", "enum": [ "facebook", "instagram" ], "example": "instagram" }, "competitors": { "description": "Each entry needs competitor_id (the page or account id on the platform) and name; take them from competitor-search. To chart the caller's own page alongside the others, include it here as one of the entries - there is no separate own-account field.", "type": "array", "items": { "properties": { "competitor_id": { "type": "string", "example": "17841400000000002" }, "name": { "type": "string", "example": "Nike" }, "slug": { "type": "string", "example": "nike", "nullable": true }, "image": { "type": "string", "nullable": true } }, "type": "object" }, "minItems": 1, "example": [ { "competitor_id": "17841400000000001", "name": "Our Brand", "slug": "ourbrand", "image": "https://scontent.cdninstagram.com/v/ourbrand.jpg" }, { "competitor_id": "17841400000000002", "name": "Nike", "slug": "nike", "image": "https://scontent.cdninstagram.com/v/nike.jpg" } ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Report created", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error, or one or more competitors cannot be tracked. In the second case `error_code` is COMPETITOR_NOT_TRACKABLE and `untrackable_competitors` names each one with its reason, so the caller learns which page is the problem rather than saving a report that silently produces nothing.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "error_code": { "type": "string", "example": "COMPETITOR_NOT_TRACKABLE" }, "untrackable_competitors": { "type": "array", "items": { "properties": { "competitor_id": { "type": "string" }, "name": { "type": "string" }, "reason": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/competitor-reports/{report_id}": { "get": { "tags": [ "πŸ“Š Competitor Reports" ], "summary": "Read one saved competitor report", "operationId": "getCompetitorReport", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "report_id", "in": "path", "description": "From list_competitor_reports. This is the same id passed as competitor_report_id to the comparison endpoints.", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "200": { "description": "The report and the pages it tracks. The array is the whole comparison set: if the caller's own page is charted alongside the competitors, it is one of these entries - there is no separate own-account field.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "competitor_report": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "No such report in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "πŸ“Š Competitor Reports" ], "summary": "Update a saved competitor report", "operationId": "updateCompetitorReport", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "report_id", "in": "path", "description": "From list_competitor_reports. This is the same id passed as competitor_report_id to the comparison endpoints.", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "platform_type", "competitors" ], "properties": { "name": { "type": "string", "example": "Key rivals (Q3)" }, "platform_type": { "type": "string", "enum": [ "facebook", "instagram" ], "example": "instagram" }, "competitors": { "description": "The FULL list the report should have after the update - it replaces what was there. Omitting a competitor removes it; adding one appends it. Send the existing entries back unchanged to keep them.", "type": "array", "items": { "type": "object" }, "minItems": 1, "example": [ { "competitor_id": "17841400000000001", "name": "Our Brand", "slug": "ourbrand" }, { "competitor_id": "17841400000000003", "name": "Adidas", "slug": "adidas" } ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Report updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such report in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“Š Competitor Reports" ], "summary": "Delete a saved competitor report", "operationId": "deleteCompetitorReport", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "report_id", "in": "path", "description": "From list_competitor_reports. This is the same id passed as competitor_report_id to the comparison endpoints.", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "200": { "description": "Report deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such report in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/competitor-search": { "get": { "tags": [ "πŸ“Š Competitor Reports" ], "summary": "Search a platform for an account to track as a competitor", "operationId": "searchCompetitors", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "platform_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "facebook", "instagram" ], "example": "instagram" } }, { "name": "search", "in": "query", "description": "A handle, page name, or profile URL.", "required": true, "schema": { "type": "string", "example": "nike" } } ], "responses": { "200": { "description": "Matches found. An empty `results` with `not_trackable: false` means the platform returned no match for the term. An empty `results` with `not_trackable: true` means the account exists but cannot be tracked - Instagram only exposes business and creator accounts, so a personal or private profile is ineligible - and `reason` says which. The two need different fixes from the caller, so they are not both reported as 'no results'.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "not_trackable": { "description": "True when the account was found but cannot be tracked.", "type": "boolean" }, "reason": { "description": "Why it cannot be tracked. Present only when not_trackable is true.", "type": "string", "nullable": true }, "results": { "type": "array", "items": { "properties": { "competitor_id": { "description": "Pass this in the competitors array when creating a report", "type": "string" }, "name": { "type": "string" }, "image": { "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/summary": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook summary KPIs β€” current vs previous period", "operationId": "facebookAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Facebook page and post metrics broken into `current`, `previous`, absolute `difference`, and `percentage` change. Each block carries the same metric keys.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "fan_count": 42500, "page_follows": 41800, "talking_about_count": 1240, "page_impressions": 185000, "page_impressions_paid": 62000, "page_impressions_organic": 123000, "page_engagements": 3800, "page_positive_feedback": 520, "page_negative_feedback": 48, "total_posts": 22, "post_engagement": 2950, "post_reactions": 1820, "post_comments": 480, "post_clicks": 1650, "post_impressions": 145000, "post_reach": 98000, "post_reposts": 320, "post_positive_sentiment": 1480, "post_negative_sentiment": 210 }, "previous": { "fan_count": 40200, "page_follows": 39600, "talking_about_count": 1100, "page_impressions": 168000, "page_impressions_paid": 55000, "page_impressions_organic": 113000, "page_engagements": 3400, "page_positive_feedback": 470, "page_negative_feedback": 42, "total_posts": 19, "post_engagement": 2650, "post_reactions": 1640, "post_comments": 420, "post_clicks": 1480, "post_impressions": 132000, "post_reach": 88000, "post_reposts": 290, "post_positive_sentiment": 1320, "post_negative_sentiment": 190 }, "difference": { "fan_count": 2300, "page_follows": 2200, "talking_about_count": 140, "page_impressions": 17000, "page_impressions_paid": 7000, "page_impressions_organic": 10000, "page_engagements": 400, "page_positive_feedback": 50, "page_negative_feedback": 6, "total_posts": 3, "post_engagement": 300, "post_reactions": 180, "post_comments": 60, "post_clicks": 170, "post_impressions": 13000, "post_reach": 10000, "post_reposts": 30, "post_positive_sentiment": 160, "post_negative_sentiment": 20 }, "percentage": { "fan_count": 5.7, "page_follows": 5.6, "talking_about_count": 12.7, "page_impressions": 10.1, "page_impressions_paid": 12.7, "page_impressions_organic": 8.8, "page_engagements": 11.8, "page_positive_feedback": 10.6, "page_negative_feedback": 14.3, "total_posts": 15.8, "post_engagement": 11.3, "post_reactions": 11, "post_comments": 14.3, "post_clicks": 11.5, "post_impressions": 9.8, "post_reach": 11.4, "post_reposts": 10.3, "post_positive_sentiment": 12.1, "post_negative_sentiment": 10.5 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/audience-growth": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook fan / follower growth over time", "operationId": "facebookAnalyticsAudienceGrowth", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Audience growth series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "audience_growth": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "fan_count": { "type": "integer", "example": 42500 }, "page_fans_daily": { "type": "integer", "example": 150 }, "page_fans_by_like": { "type": "integer", "example": 155 }, "page_fans_by_unlike": { "type": "integer", "example": 5 }, "page_impressions": { "type": "integer", "example": 6800 }, "page_engagements": { "type": "integer", "example": 460 } }, "type": "object" } }, "audience_growth_rollup": { "description": "Keyed by period: `current` for the requested range, `previous` for the equivalent prior range.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "avg_page_fans_by_like": 4.2, "avg_page_fans_by_unlike": 0.5, "fan_count": 42500, "talking_about_count": 1240, "post_count": 22 }, "previous": { "avg_page_fans_by_like": 3.8, "avg_page_fans_by_unlike": 0.4, "fan_count": 40200, "talking_about_count": 1100, "post_count": 19 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/publishing-behaviour": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook engagement by impression type over time", "operationId": "facebookAnalyticsPublishingBehaviour", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "text", "link", "images", "videos", "carousel", "share", "reels", "others" ] } }, "example": "images,videos" } ], "responses": { "200": { "description": "Publishing behaviour series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "publishing_behaviour": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "reactions_engagement": { "type": "integer", "example": 490 }, "comments_engagement": { "type": "integer", "example": 138 }, "shares_engagement": { "type": "integer", "example": 90 }, "paid_impressions": { "type": "integer", "example": 19500 }, "organic_impressions": { "type": "integer", "example": 39000 }, "viral_impressions": { "type": "integer", "example": 7900 }, "paid_reach": { "type": "integer", "example": 16500 }, "organic_reach": { "type": "integer", "example": 32000 }, "viral_reach": { "type": "integer", "example": 6700 }, "post_count": { "type": "integer", "example": 2 } }, "type": "object" } }, "publishing_behaviour_rollup": { "description": "Keyed by period: `current` for the requested range, `previous` for the equivalent prior range.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "post_count": 22, "post_engagement": 2950, "post_reactions": 1820, "post_comments": 480, "post_clicks": 1650, "post_impressions": 145000, "post_shares": 320 }, "previous": { "post_count": 19, "post_engagement": 2650, "post_reactions": 1640, "post_comments": 420, "post_clicks": 1480, "post_impressions": 132000, "post_shares": 290 } } }, "publishing_behaviour_breakdown": { "description": "The same period split by post type, one entry per type actually used plus a trailing `total` row whose values are the column-wise sum. Keyed by period like the rollup above. Reach is the sum of each post's own unique reach, not the page's deduplicated reach.", "properties": { "current": { "type": "array", "items": { "type": "object" } }, "previous": { "type": "array", "items": { "type": "object" } } }, "type": "object", "example": { "current": [ { "media_type": "images", "total_posts": 14, "engagement": 1980, "reactions": 1240, "comments": 310, "shares": 190, "clicks": 240, "impressions": 96000, "reach": 61000 }, { "media_type": "reels", "total_posts": 8, "engagement": 970, "reactions": 580, "comments": 170, "shares": 130, "clicks": 90, "impressions": 49000, "reach": 32000 }, { "media_type": "total", "total_posts": 22, "engagement": 2950, "reactions": 1820, "comments": 480, "shares": 320, "clicks": 330, "impressions": 145000, "reach": 93000 } ], "previous": [] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/top-posts": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook top posts (overview widget)", "operationId": "facebookAnalyticsOverviewTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "engagement", "post_engagement", "total_engagement", "impressions", "post_impressions", "reach", "post_impressions_unique", "views", "post_video_views", "created_time", "comments", "shares", "post_clicks", "total", "published_at" ], "example": "post_engagement" } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "text", "link", "images", "videos", "carousel", "share", "reels", "others" ] } }, "example": "images,videos" } ], "responses": { "200": { "description": "Top posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "type": "object", "example": { "platform_account_name": "ContentStudio", "platform_id": "111000111000", "post_id": "111000111000_902341", "permalink": "https://facebook.com/111000111000/posts/902341", "status_type": "added_photos", "media_type": "images", "video_id": "", "caption": "New year, new playbook.", "description": "Quick rundown of the 2026 roadmap.", "thumbnail": "https://scontent.xx.fbcdn.net/v/...", "link": "https://contentstudio.io/blog/2026-roadmap", "like_count": 482, "reaction_love": 88, "reaction_haha": 12, "reaction_wow": 14, "reaction_sad": 1, "reaction_angry": 0, "reaction_count": 597, "share_count": 14, "comment_count": 37, "post_clicks": 88, "post_engagement": 621, "post_engaged_users": 540, "day_of_week": "Thursday", "hour_of_day": 14, "created_at": "2026-01-22T14:08:00Z", "published_at": "2026-01-22T09:08:00-05:00", "saved_at": "2026-01-22T14:08:12Z", "impression_count": 4820, "impression_count_unique": 3940, "impression_count_paid": 0, "impression_count_paid_unique": 0, "impression_count_organic": 4500, "impression_count_organic_unique": 3700, "impression_count_viral": 320, "impression_count_viral_unique": 240, "post_video_views": 0, "media_assets": [ { "media_id": "media_8821", "caption": "Cover image", "link": "https://scontent.xx.fbcdn.net/v/...", "asset_type": "photo", "call_to_action": "LEARN_MORE", "created_at": "2026-01-22T14:08:00Z" } ] } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/sorted-top-posts": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook top posts with media_type filter", "operationId": "facebookAnalyticsGetTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "post_engagement", "engagement", "total_engagement", "created_time", "published_at", "comments", "shares", "post_clicks", "impressions", "post_impressions", "reach", "post_impressions_unique", "views", "post_video_views", "total", "caption", "media_type" ], "example": "post_impressions" } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": "videos,reels" } ], "responses": { "200": { "description": "Top posts retrieved successfully (same shape as /top-posts)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "description": "Same shape as /top-posts; filtered by media_type.", "type": "array", "items": { "type": "object", "example": { "platform_account_name": "ContentStudio", "platform_id": "111000111000", "post_id": "111000111000_889123", "permalink": "https://facebook.com/111000111000/posts/889123", "status_type": "added_video", "media_type": "videos", "video_id": "884921", "caption": "Behind the scenes: launch week.", "description": "", "thumbnail": "https://scontent.xx.fbcdn.net/v/...", "link": "", "like_count": 720, "reaction_love": 132, "reaction_haha": 8, "reaction_wow": 24, "reaction_sad": 0, "reaction_angry": 0, "reaction_count": 884, "share_count": 32, "comment_count": 56, "post_clicks": 142, "post_engagement": 940, "post_engaged_users": 820, "day_of_week": "Wednesday", "hour_of_day": 11, "created_at": "2026-01-14T11:02:00Z", "published_at": "2026-01-14T06:02:00-05:00", "saved_at": "2026-01-14T11:02:08Z", "impression_count": 24180, "impression_count_unique": 18420, "impression_count_paid": 0, "impression_count_paid_unique": 0, "impression_count_organic": 22300, "impression_count_organic_unique": 17120, "impression_count_viral": 1880, "impression_count_viral_unique": 1300, "post_video_views": 18420, "media_assets": [ { "media_id": "media_9914", "caption": "Launch teaser", "link": "https://scontent.xx.fbcdn.net/v/...", "asset_type": "video", "call_to_action": "WATCH_MORE", "created_at": "2026-01-14T11:02:00Z" } ] } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/post": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Get a single Facebook post by ID", "operationId": "facebookAnalyticsSinglePost", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "post_id", "in": "query", "description": "Platform-native identifier of the post.", "required": true, "schema": { "type": "string", "example": "111000111000_902341" } } ], "responses": { "200": { "description": "Single post retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "post": { "description": "Same shape as a /top-posts item.", "type": "object", "example": { "platform_account_name": "ContentStudio", "platform_id": "111000111000", "post_id": "111000111000_902341", "permalink": "https://facebook.com/111000111000/posts/902341", "status_type": "added_photos", "media_type": "images", "video_id": "", "caption": "New year, new playbook.", "description": "Quick rundown of the 2026 roadmap.", "thumbnail": "https://scontent.xx.fbcdn.net/v/...", "link": "https://contentstudio.io/blog/2026-roadmap", "like_count": 482, "reaction_love": 88, "reaction_haha": 12, "reaction_wow": 14, "reaction_sad": 1, "reaction_angry": 0, "reaction_count": 597, "share_count": 14, "comment_count": 37, "post_clicks": 88, "post_engagement": 621, "post_engaged_users": 540, "day_of_week": "Thursday", "hour_of_day": 14, "created_at": "2026-01-22T14:08:00Z", "published_at": "2026-01-22T09:08:00-05:00", "saved_at": "2026-01-22T14:08:12Z", "impression_count": 4820, "impression_count_unique": 3940, "impression_count_paid": 0, "impression_count_paid_unique": 0, "impression_count_organic": 4500, "impression_count_organic_unique": 3700, "impression_count_viral": 320, "impression_count_viral_unique": 240, "post_video_views": 0, "media_assets": [ { "media_id": "media_8821", "caption": "Cover image", "link": "https://scontent.xx.fbcdn.net/v/...", "asset_type": "photo", "call_to_action": "LEARN_MORE", "created_at": "2026-01-22T14:08:00Z" } ] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/impressions": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook page impressions over time", "operationId": "facebookAnalyticsImpressions", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Page impressions series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "impressions": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "page_impressions": { "type": "integer", "example": 5020 } }, "type": "object" } }, "impressions_rollup": { "description": "Keyed by period: `current` for the requested range, `previous` for the equivalent prior range.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "total_impressions": 185000, "avg_impressions_per_day": 5968, "avg_impressions_per_week": 41776 }, "previous": { "total_impressions": 168000, "avg_impressions_per_day": 5419, "avg_impressions_per_week": 37933 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/engagement": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook page engagements over time", "operationId": "facebookAnalyticsEngagement", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Page engagements series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "engagement": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "page_engagements": { "type": "integer", "example": 300 } }, "type": "object" } }, "engagement_rollup": { "description": "Keyed by period: `current` for the requested range, `previous` for the equivalent prior range.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "page_engagements": 3800, "avg_engagements_per_day": 122.6, "avg_engagements_per_week": 858.2 }, "previous": { "page_engagements": 3400, "avg_engagements_per_day": 109.7, "avg_engagements_per_week": 767.9 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/reels-performance": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook Reels performance over time", "operationId": "facebookAnalyticsReels", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Reels analytics series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "reels": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "total_reels": { "type": "integer", "example": 3 }, "total_seconds_watched": { "type": "number", "example": 6840.2 }, "initial_plays": { "type": "integer", "example": 5120 }, "engagement": { "type": "integer", "example": 210 }, "reactions": { "type": "integer", "example": 134 }, "comments": { "type": "integer", "example": 52 }, "shares": { "type": "integer", "example": 24 } }, "type": "object" } }, "reels_rollup": { "description": "Keyed by period: `current` for the requested range, `previous` for the equivalent prior range.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "total_reels": 6, "average_seconds_watched": 2245.6, "total_seconds_watched": 13470, "initial_plays": 9770, "reach": 7820, "engagement": 428, "reactions": 277, "comments": 102, "shares": 49 }, "previous": { "total_reels": 4, "average_seconds_watched": 1980.3, "total_seconds_watched": 7921, "initial_plays": 6240, "reach": 5180, "engagement": 312, "reactions": 198, "comments": 74, "shares": 40 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/video-insights": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook video view time and plays over time", "operationId": "facebookAnalyticsVideoInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Video insights series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "video_insights": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "total_view_time": { "type": "number", "example": 21240.7 }, "organic_view_time": { "type": "number", "example": 20800 }, "paid_view_time": { "type": "number", "example": 440.7 }, "total_views": { "type": "integer", "example": 7240 }, "organic_views": { "type": "integer", "example": 7100 }, "paid_views": { "type": "integer", "example": 140 }, "comments": { "type": "integer", "example": 32 }, "reactions": { "type": "integer", "example": 210 }, "shares": { "type": "integer", "example": 18 }, "total_posts": { "type": "integer", "example": 3 } }, "type": "object" } }, "video_rollup": { "description": "Keyed by period: `current` for the requested range, `previous` for the equivalent prior range.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "total_view_time": 54481.2, "organic_view_time": 52700, "paid_view_time": 1781.2, "total_views": 17980, "organic_views": 17480, "paid_views": 500, "comments": 75, "reactions": 495, "shares": 39, "total_posts": 6 }, "previous": { "total_view_time": 46220.8, "organic_view_time": 44900, "paid_view_time": 1320.8, "total_views": 14820, "organic_views": 14380, "paid_views": 440, "comments": 62, "reactions": 412, "shares": 32, "total_posts": 5 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/audience-location": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook audience location (country/city breakdown)", "description": "Country and city breakdown of the page's followers. Age and gender are not available: Meta deprecated the page_fans_gender_age Page Insights metric on 2025-11-15 with no replacement, so the /demographics and /overview-demographics endpoints were removed. See https://developers.facebook.com/docs/platforminsights/page/deprecated-metrics", "operationId": "facebookAnalyticsAudienceLocation", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "country", "in": "query", "description": "Restrict `audience_city` to the cities in one country (ISO 3166-1 alpha-2). Facebook writes the country into each city label, so no derivation is needed. Omit for the global city list. A country with no cities returns an empty list rather than an error. `audience_country` and `available_countries` are unaffected.", "required": false, "schema": { "type": "string", "example": "NZ" } } ], "responses": { "200": { "description": "Audience location retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "audience_country": { "description": "Followers by country, from page_follows_country.", "type": "object", "example": { "US": 18000, "GB": 5200, "CA": 3100, "AU": 2400, "IN": 2100 } }, "audience_city": { "description": "Followers by city, from page_follows_city. The label already contains the country. Filtered to one country when `country` is supplied.", "type": "object", "example": { "New York, NY": 3200, "Los Angeles, CA": 2800, "London, United Kingdom": 2100, "Sydney, Australia": 1900 } }, "available_countries": { "description": "Country codes accepted by `country`, ordered by follower count. Only countries with at least one city appear.", "type": "array", "items": { "type": "string", "example": "NZ" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/ai-insights": { "get": { "tags": [ "πŸ“˜ Facebook" ], "summary": "Facebook AI-generated insights", "description": "Two insight types over the same dataset, selected with `type`: `aiInsightsSummary` is a compact summary and `aiInsightsDetailed` is the full read-out. Generation is asynchronous: the first call returns a `generating` status, and repeating the same request returns the insight once it is ready. Results are cached for 24 hours, so a repeated call is normally immediate.", "operationId": "facebookAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "AI insights type key. `aiInsightsSummary` backs the Overview summary card and `aiInsightsDetailed` the AI Insights tab.", "required": true, "schema": { "type": "string", "default": "aiInsightsDetailed", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5 } }, { "name": "language", "in": "query", "description": "Response language (ISO 639-1)", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "AI insights retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "description": "AI-generated insight body, returned verbatim from the analytics service. The shape follows `type`: `aiInsightsSummary` returns `health_score`, `health_label`, `status_summary`, `summary_text` and exactly 3 `highlights`; `aiInsightsDetailed` returns `status_headline`, `status_reason`, `status_tone`, 3 `executive_summary` bullets, 6 `metrics`, `whats_happening` (an intro plus root-cause/effect/impact steps), 3-4 `actions` and 3 `suggested_prompts`. Every field is model-generated, so treat each as optional.", "type": "object", "example": { "success": true, "health_score": 78, "health_label": "Good", "status_summary": "Engagement is climbing", "summary_text": "Video posts drove **2.4x** the engagement of images this period.", "highlights": [ "...", "...", "..." ], "confidence": "High" }, "additionalProperties": true }, "message": { "type": "string", "example": "", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/data-table-metrics": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Per-competitor aggregate metrics table", "operationId": "facebookCompetitorDataTableMetrics", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/posting-activity-graph-by-types": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Posting activity over time split by media type", "operationId": "facebookCompetitorPostingActivityGraphByTypes", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/posting-activity-by-specific-type": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Posting activity for a specific media type", "operationId": "facebookCompetitorPostingActivityBySpecificType", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "description": "Comma-separated post-type filter.", "required": false, "schema": { "type": "string", "example": "photo,video" } } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/post-react-distribution": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Reaction type distribution for a single competitor", "operationId": "facebookCompetitorPostReactDistribution", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/post-react-distribution-by-company": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Reaction distribution grouped by competitor page", "operationId": "facebookCompetitorPostReactDistributionByCompany", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/post-type-distribution": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Post type distribution across competitors", "operationId": "facebookCompetitorPostTypeDistribution", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/top-and-least-performing-posts": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Top and least performing competitor posts", "operationId": "facebookCompetitorTopAndLeastPerformingPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "sort_order", "in": "query", "description": "Sort direction for the ranked lists.", "required": false, "schema": { "type": "string", "example": "desc" } } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/top-hashtags": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Most-used hashtags across competitors", "operationId": "facebookCompetitorTopHashtags", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/individual-hashtag-data": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Posts for a specific competitor hashtag", "operationId": "facebookCompetitorIndividualHashtagData", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsHashtag" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/biography-data": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Competitor page bio and profile info", "operationId": "facebookCompetitorBiographyData", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/followers-growth-comparison": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Follower growth comparison across competitors", "operationId": "facebookCompetitorFollowersGrowthComparison", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/post-engagement-over-time": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Post engagement trend for a single competitor", "operationId": "facebookCompetitorPostEngagementOverTime", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/facebook/competitor/post-engagement-by-competitor": { "get": { "tags": [ "πŸ“˜ Facebook Competitors" ], "summary": "Post engagement comparison across all competitors", "operationId": "facebookCompetitorPostEngagementByCompetitor", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/gmb/summary": { "get": { "tags": [ "πŸ“ Google My Business" ], "summary": "GMB summary KPIs β€” current vs previous period", "operationId": "gmbAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Location metrics broken into `current`, `previous`, absolute `difference`, and `percentage` change. Each block carries the same metric keys.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "total_impressions": 12400, "search_impressions": 7800, "maps_impressions": 4600, "website_clicks": 320, "call_clicks": 145, "direction_requests": 210, "other_actions": 55, "total_reviews": 28, "average_rating": 4.6, "total_posts": 12 }, "previous": { "total_impressions": 11200, "search_impressions": 7100, "maps_impressions": 4100, "website_clicks": 290, "call_clicks": 130, "direction_requests": 190, "other_actions": 48, "total_reviews": 22, "average_rating": 4.5, "total_posts": 10 }, "difference": { "total_impressions": 1200, "search_impressions": 700, "maps_impressions": 500, "website_clicks": 30, "call_clicks": 15, "direction_requests": 20, "other_actions": 7, "total_reviews": 6, "average_rating": 0.1, "total_posts": 2 }, "percentage": { "total_impressions": 10.7, "search_impressions": 9.9, "maps_impressions": 12.2, "website_clicks": 10.3, "call_clicks": 11.5, "direction_requests": 10.5, "other_actions": 14.6, "total_reviews": 27.3, "average_rating": 2.2, "total_posts": 20 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/gmb/impressions": { "get": { "tags": [ "πŸ“ Google My Business" ], "summary": "GMB impressions breakdown by channel and device over time", "operationId": "gmbAnalyticsImpressions", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Impressions series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "impressions": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "desktop_maps": { "type": "integer", "example": 420 }, "desktop_search": { "type": "integer", "example": 890 }, "mobile_maps": { "type": "integer", "example": 1650 }, "mobile_search": { "type": "integer", "example": 2240 }, "total_impressions": { "type": "integer", "example": 5200 } }, "type": "object" } }, "impressions_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "total_impressions": 12400, "desktop_maps": 3200, "desktop_search": 4600, "mobile_maps": 8400, "mobile_search": 11200, "avg_impressions": 400 }, "previous": { "total_impressions": 11200, "desktop_maps": 2900, "desktop_search": 4200, "mobile_maps": 7600, "mobile_search": 10100, "avg_impressions": 361.3 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/gmb/actions": { "get": { "tags": [ "πŸ“ Google My Business" ], "summary": "GMB customer actions (clicks, calls, directions) over time", "operationId": "gmbAnalyticsActions", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Actions series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "actions": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "call_clicks": { "type": "integer", "example": 12 }, "website_clicks": { "type": "integer", "example": 28 }, "direction_requests": { "type": "integer", "example": 18 }, "other_actions": { "type": "integer", "example": 5 } }, "type": "object" } }, "actions_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "total_call_clicks": 145, "total_website_clicks": 320, "total_direction_requests": 210, "total_other_actions": 55, "avg_actions": 23.5 }, "previous": { "total_call_clicks": 130, "total_website_clicks": 290, "total_direction_requests": 190, "total_other_actions": 48, "avg_actions": 21.2 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/gmb/search-keywords": { "get": { "tags": [ "πŸ“ Google My Business" ], "summary": "GMB top search keywords that surfaced the listing", "operationId": "gmbAnalyticsSearchKeywords", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" } ], "responses": { "200": { "description": "Search keywords retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "search_keywords": { "type": "array", "items": { "properties": { "keyword": { "type": "string", "example": "coffee shop near me" }, "impressions_value": { "type": "integer", "example": 420 }, "impressions_threshold": { "type": "integer", "example": 500 }, "keyword_month": { "type": "string", "example": "2026-01" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/gmb/top-posts": { "get": { "tags": [ "πŸ“ Google My Business" ], "summary": "GMB top-performing posts", "operationId": "gmbAnalyticsTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "order_by", "in": "query", "description": "Sort field. Text columns (caption, topic_type, state, post_type) sort alphabetically; anything else falls back to created_at (newest first).", "required": false, "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "published_at", "caption", "summary", "topic_type", "state", "post_type" ] } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "topic_type", "in": "query", "description": "Comma-separated list of topic types to filter by (e.g. STANDARD,OFFER,EVENT).", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": "STANDARD,OFFER" } ], "responses": { "200": { "description": "Top posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "posts": { "type": "array", "items": { "properties": { "post_name": { "type": "string", "example": "accounts/123/locations/456/localPosts/789" }, "summary": { "type": "string", "example": "Check out our new seasonal menu!" }, "state": { "type": "string", "example": "LIVE" }, "topic_type": { "type": "string", "example": "STANDARD" }, "search_url": { "type": "string", "example": "https://g.page/r/..." }, "media_names": { "type": "array", "items": { "type": "string" } }, "media_formats": { "type": "array", "items": { "type": "string" } }, "media_google_urls": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "example": "2026-01-12T10:00:00Z" }, "published_at": { "description": "Publish time as RFC 3339 in the request timezone; null when unknown.", "type": "string", "format": "date-time", "example": "2026-01-12T05:00:00-05:00", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/gmb/post": { "get": { "tags": [ "πŸ“ Google My Business" ], "summary": "Get a single GMB post by ID", "operationId": "gmbAnalyticsSinglePost", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "name": "post_id", "in": "query", "description": "Platform-native identifier of the post.", "required": true, "schema": { "type": "string", "example": "accounts/123/locations/456/localPosts/789" } } ], "responses": { "200": { "description": "Single post retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "post": { "description": "Same shape as a /top-posts item.", "type": "object", "example": { "post_name": "accounts/123/locations/456/localPosts/789", "summary": "Check out our new seasonal menu!", "state": "LIVE", "topic_type": "STANDARD", "search_url": "https://g.page/r/...", "media_names": [], "media_formats": [], "media_google_urls": [], "created_at": "2026-01-12T10:00:00Z" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/gmb/publishing-behaviour": { "get": { "tags": [ "πŸ“ Google My Business" ], "summary": "GMB posts published over time and topic-type breakdown", "operationId": "gmbAnalyticsPublishingBehavior", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Publishing behaviour retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "publishing_behaviour": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "post_count": { "type": "integer", "example": 3 } }, "type": "object" } }, "topic_types": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "STANDARD" }, "count": { "type": "integer", "example": 8 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/gmb/reviews": { "get": { "tags": [ "πŸ“ Google My Business" ], "summary": "GMB reviews β€” ratings, distribution, and daily activity", "operationId": "gmbAnalyticsReviews", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Reviews retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "reviews": { "properties": { "avg_rating": { "type": "number", "example": 4.6 }, "total_reviews": { "type": "integer", "example": 28 }, "star_distribution": { "type": "object", "example": { "1": 1, "2": 2, "3": 3, "4": 8, "5": 14 }, "additionalProperties": { "type": "integer" } }, "daily_reviews": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "daily_reviews": { "type": "integer", "example": 2 } }, "type": "object" } }, "reviews_list": { "type": "array", "items": { "properties": { "review_id": { "type": "string", "example": "ABC123" }, "reviewer_display_name": { "type": "string", "example": "Jane Doe" }, "reviewer_profile_photo_url": { "type": "string", "example": "https://example.com/photo.jpg" }, "star_rating": { "type": "integer", "example": 5 }, "comment": { "type": "string", "example": "Great coffee and service!" }, "reply_comment": { "type": "string", "example": "Thank you so much!" }, "created_at": { "type": "string", "example": "2026-01-28T09:00:00Z" } }, "type": "object" } } }, "type": "object" }, "reviews_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "total_reviews": 28, "avg_rating": 4.6 }, "previous": { "total_reviews": 22, "avg_rating": 4.5 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/gmb/media-activity": { "get": { "tags": [ "πŸ“ Google My Business" ], "summary": "GMB media (photo/video) activity over time", "operationId": "gmbAnalyticsMediaActivity", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Media activity retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "media_activity": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "photo_count": { "type": "integer", "example": 4 }, "video_count": { "type": "integer", "example": 1 } }, "type": "object" } }, "media_activity_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "total_photos": 48, "total_videos": 12, "avg_media": 1.94 }, "previous": { "total_photos": 42, "total_videos": 9, "avg_media": 1.65 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/gmb/ai-insights": { "get": { "tags": [ "πŸ“ Google My Business" ], "summary": "GMB AI-generated insights", "description": "Two insight types over the same dataset, selected with `type`: `aiInsightsSummary` is a compact summary and `aiInsightsDetailed` is the full read-out. Generation is asynchronous: the first call returns a `generating` status, and repeating the same request returns the insight once it is ready. Results are cached for 24 hours, so a repeated call is normally immediate.", "operationId": "gmbAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "AI insights type key. `aiInsightsSummary` backs the Overview summary card and `aiInsightsDetailed` the AI Insights tab.", "required": true, "schema": { "type": "string", "default": "aiInsightsDetailed", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5 } }, { "name": "language", "in": "query", "description": "Response language (ISO 639-1)", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "AI insights retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "description": "AI-generated insight body, returned verbatim from the analytics service. The shape follows `type`: `aiInsightsSummary` returns `health_score`, `health_label`, `status_summary`, `summary_text` and exactly 3 `highlights`; `aiInsightsDetailed` returns `status_headline`, `status_reason`, `status_tone`, 3 `executive_summary` bullets, 6 `metrics`, `whats_happening` (an intro plus root-cause/effect/impact steps), 3-4 `actions` and 3 `suggested_prompts`. Every field is model-generated, so treat each as optional.", "type": "object", "example": { "success": true, "health_score": 78, "health_label": "Good", "status_summary": "Discovery is steady", "summary_text": "Mobile Maps impressions are the top discovery channel this period.", "highlights": [ "...", "...", "..." ], "confidence": "High" }, "additionalProperties": true }, "message": { "type": "string", "example": "", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/accounts": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "List connected Google Ads accounts", "description": "The starting point for every other Google Ads endpoint: it returns the `account_id` they all require, along with the account's currency. Only ad accounts the API key's owner may read are returned.", "operationId": "googleAdsAnalyticsAccounts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsSearch" } ], "responses": { "200": { "description": "Connected Google Ads accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsAccountsList" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/summary": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Google Ads headline KPIs β€” current vs previous period", "description": "Spend, impressions, clicks, CTR, average CPC and conversions for the requested range, each alongside the equivalent prior range and the absolute and percentage change. Monetary values are in currency.", "operationId": "googleAdsAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "currency": { "type": "string", "example": "USD" }, "account_id": { "type": "string", "example": "1234567890" }, "summary": { "description": "Four buckets carrying the same metric keys: `current`, `previous`, absolute `difference` and `percentage` change.", "type": "object", "example": { "current": { "spend": 8420.1, "impressions": 412000, "clicks": 9840, "ctr": 2.39, "avg_cpc": 0.86, "conversions": 312.5 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/performance-over-time": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Daily time series for one or more metrics", "description": "Ask for several metrics at once with `metrics=spend,clicks,conversions` and they arrive under `series`, keyed by metric name β€” one request, one query, however many metrics. A single-metric request (`metric=spend`) returns the flat `performance_trend` array instead. Granularity is daily; it is the only granularity the ads data supports.", "operationId": "googleAdsAnalyticsPerformanceOverTime", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "metrics", "in": "query", "description": "Comma-separated metric list. Unknown names are ignored. When omitted, `metric` is used.", "required": false, "schema": { "type": "string", "example": "spend,clicks,conversions" } }, { "name": "metric", "in": "query", "description": "Single metric, used only when `metrics` is absent.", "required": false, "schema": { "type": "string", "default": "spend", "enum": [ "spend", "impressions", "clicks", "conversions", "conversion_rate", "cost_per_conversion", "avg_cpc", "ctr", "cpm" ] } } ], "responses": { "200": { "description": "Retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "currency": { "type": "string", "example": "USD" }, "metric": { "type": "string", "example": "spend" }, "total": { "type": "number", "format": "float", "example": 8420.1 }, "performance_trend": { "type": "array", "items": { "$ref": "#/components/schemas/AdsTrendPoint" } }, "series": { "description": "Present only for a multi-metric request. Keyed by metric name.", "type": "object" }, "totals": { "description": "Range total per metric. Present only for a multi-metric request.", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/performance-by-level": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "One metric broken down by campaign, ad group or ad", "operationId": "googleAdsAnalyticsPerformanceByLevel", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "level", "in": "query", "required": false, "schema": { "type": "string", "default": "campaign", "enum": [ "campaign", "adgroup", "ad" ] } }, { "name": "metric", "in": "query", "required": false, "schema": { "type": "string", "default": "spend", "enum": [ "spend", "impressions", "clicks", "conversions", "conversion_rate", "cost_per_conversion", "avg_cpc", "ctr", "cpm" ] } } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/performance-by-type": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "One metric broken down by campaign type", "description": "Search, Display, Video, Shopping, Performance Max and the rest β€” Google's advertising channel types. Meta Ads has no equivalent breakdown.", "operationId": "googleAdsAnalyticsPerformanceByType", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "metric", "in": "query", "required": false, "schema": { "type": "string", "default": "spend", "enum": [ "spend", "impressions", "clicks", "conversions", "conversion_rate", "cost_per_conversion", "avg_cpc", "ctr", "cpm" ] } } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/campaigns": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Campaigns with per-campaign metrics", "description": "Paginated with `limit`/`offset`. `total` is the number of campaigns matching the filters, so page through by advancing `offset` until it reaches `total`. Filter by campaign type with `type`; accepted values for `status` and `type` are returned in each response under `available_statuses` and `available_types`.", "operationId": "googleAdsAnalyticsCampaigns", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsSearch" }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" }, { "$ref": "#/components/parameters/AdsStatus" }, { "name": "type", "in": "query", "description": "Advertising channel type filter. Accepted values are returned in `available_types`.", "required": false, "schema": { "type": "string", "example": "SEARCH" } } ], "responses": { "200": { "description": "Retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "currency": { "type": "string", "example": "USD" }, "total": { "type": "integer", "example": 42 }, "limit": { "type": "integer", "example": 25 }, "offset": { "type": "integer", "example": 0 }, "available_statuses": { "type": "array", "items": { "type": "string" }, "example": [ "ENABLED", "PAUSED" ] }, "available_types": { "type": "array", "items": { "type": "string" }, "example": [ "SEARCH", "PERFORMANCE_MAX" ] }, "campaigns": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/ad-groups": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Ad groups with per-ad-group metrics", "description": "Pass `campaign_id` to drill into one campaign's ad groups; omit it for every ad group in the account. This is the Google equivalent of Meta's ad sets.", "operationId": "googleAdsAnalyticsAdGroups", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsSearch" }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" }, { "$ref": "#/components/parameters/AdsCampaignId" }, { "$ref": "#/components/parameters/AdsStatus" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "example": "SEARCH" } } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/ads": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Ads with per-ad metrics", "description": "Scope with `campaign_id`, `ad_group_id`, both, or neither.", "operationId": "googleAdsAnalyticsAds", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsSearch" }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" }, { "$ref": "#/components/parameters/AdsCampaignId" }, { "name": "ad_group_id", "in": "query", "description": "Restrict results to a single ad group.", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AdsStatus" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "example": "SEARCH" } } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/keywords": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Keywords with per-keyword metrics", "description": "The keywords being bid on, with their match type. Scope with `campaign_id` and/or `ad_group_id`. Meta Ads has no equivalent.", "operationId": "googleAdsAnalyticsKeywords", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsSearch" }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" }, { "$ref": "#/components/parameters/AdsCampaignId" }, { "name": "ad_group_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AdsStatus" }, { "name": "match_type", "in": "query", "description": "Keyword match type. Accepted values are returned in `available_match_types`.", "required": false, "schema": { "type": "string", "enum": [ "EXACT", "PHRASE", "BROAD" ] } } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/search-terms": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Search terms with per-term metrics", "description": "The actual queries people typed that triggered an ad, as opposed to the keywords bid on. Scope with `campaign_id` and/or `ad_group_id`. Meta Ads has no equivalent.", "operationId": "googleAdsAnalyticsSearchTerms", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsSearch" }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" }, { "$ref": "#/components/parameters/AdsCampaignId" }, { "name": "ad_group_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "match_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "EXACT", "PHRASE", "BROAD" ] } } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/shopping": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Shopping campaign product performance", "description": "Per-product performance for Shopping campaigns. Returns an empty list for accounts that run none. Meta Ads has no equivalent.", "operationId": "googleAdsAnalyticsShopping", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsSearch" }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/conversions/over-time": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Conversions over time", "description": "Daily conversion counts and value. See the metric glossary for how Google counts and attributes a conversion β€” the figure is Google's own attributed count, not a raw event count.", "operationId": "googleAdsAnalyticsConversionsOverTime", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/conversions/by-action": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Conversions grouped by conversion action", "operationId": "googleAdsAnalyticsConversionsByAction", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/conversion-actions": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Conversion actions configured on the account", "description": "The conversion actions themselves β€” what the account is set up to count. Pass `campaign_id` to return only the actions a single campaign recorded conversions against.", "operationId": "googleAdsAnalyticsConversionActions", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsSearch" }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" }, { "$ref": "#/components/parameters/AdsCampaignId" } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/conversion-funnel": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Conversion funnel β€” impressions through to conversions", "operationId": "googleAdsAnalyticsConversionFunnel", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/demographics": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "Audience breakdown by age, gender and location", "description": "Unlike the Meta endpoint, this returns every demographic breakdown the account has in one response rather than taking a `breakdown` selector. Pass `country` to narrow the geographic table.", "operationId": "googleAdsAnalyticsDemographics", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "country", "in": "query", "description": "ISO country code.", "required": false, "schema": { "type": "string", "example": "US" } }, { "name": "metric", "in": "query", "required": false, "schema": { "type": "string", "default": "spend", "enum": [ "spend", "impressions", "clicks", "conversions", "conversion_rate", "cost_per_conversion", "avg_cpc", "ctr", "cpm" ] } } ], "responses": { "200": { "description": "Retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/google-ads/ai-insights": { "get": { "tags": [ "πŸ” Google Ads" ], "summary": "AI-generated insights for an ad account", "description": "Two insight types over the same dataset, selected with `type`: `aiInsightsSummary` is a compact summary and `aiInsightsDetailed` is the full read-out. Generation is asynchronous: the first call returns a `generating` status, and repeating the same request returns the insight once it is ready. Results are cached for 24 hours, so a repeated call is normally immediate.", "operationId": "googleAdsAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/GoogleAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "Which insight to generate.", "required": true, "schema": { "type": "string", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "language", "in": "query", "description": "Response language, ISO 639-1. Falls back to the request locale, then English.", "required": false, "schema": { "type": "string", "example": "en" } } ], "responses": { "200": { "description": "Either the generated insight, or an acknowledgement that generation is still running. Both are 200 β€” poll the same URL until status is true.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AdsAiInsightsGenerating" }, { "$ref": "#/components/schemas/AdsAiInsightsResult" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/summary": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram summary KPIs β€” current vs previous period", "description": "`eng_rate` is engagement as a percentage of post views (`engagement / views * 100`), matching `engagement_rate` on the overview summary endpoint. `post_views` is Instagram's account-level Views metric, so it covers all content seen in the period, not only posts published in it.", "operationId": "instagramAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Account and post metrics broken into `current`, `previous`, absolute `difference`, and `percentage` change. Each block carries the same metric keys.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "followers_count": 35800, "follows_count": 420, "profile_impressions": 92000, "profile_views": 8400, "profile_engagement": 4200, "profile_reach": 68000, "accounts_engaged": 3100, "total_posts": 24, "post_engagement": 3600, "post_reactions": 2400, "post_comments": 580, "post_saves": 720, "post_reach": 82000, "post_views": 145000, "total_stories": 45, "eng_rate": 3.8 }, "previous": { "followers_count": 33500, "follows_count": 410, "profile_impressions": 84000, "profile_views": 7600, "profile_engagement": 3800, "profile_reach": 62000, "accounts_engaged": 2800, "total_posts": 20, "post_engagement": 3200, "post_reactions": 2100, "post_comments": 510, "post_saves": 640, "post_reach": 74000, "post_views": 128000, "total_stories": 38, "eng_rate": 3.4 }, "difference": { "followers_count": 2300, "follows_count": 10, "profile_impressions": 8000, "profile_views": 800, "profile_engagement": 400, "profile_reach": 6000, "accounts_engaged": 300, "total_posts": 4, "post_engagement": 400, "post_reactions": 300, "post_comments": 70, "post_saves": 80, "post_reach": 8000, "post_views": 17000, "total_stories": 7, "eng_rate": 0.4 }, "percentage": { "followers_count": 6.9, "follows_count": 2.4, "profile_impressions": 9.5, "profile_views": 10.5, "profile_engagement": 10.5, "profile_reach": 9.7, "accounts_engaged": 10.7, "total_posts": 20, "post_engagement": 12.5, "post_reactions": 14.3, "post_comments": 13.7, "post_saves": 12.5, "post_reach": 10.8, "post_views": 13.3, "total_stories": 18.4, "eng_rate": 11.8 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/audience-growth": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram follower growth over time", "operationId": "instagramAnalyticsAudienceGrowth", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Audience growth series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "audience_growth": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "followers": { "type": "integer", "example": 34550 }, "followers_daily": { "type": "integer", "example": 170 } }, "type": "object" } }, "audience_growth_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "follower_count": 35800, "follower_gained": 2300 }, "previous": { "follower_count": 33500, "follower_gained": 1950 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/publishing-behaviour": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram post engagement by media type over time", "operationId": "instagramAnalyticsPublishingBehaviour", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "IMAGE", "VIDEO", "CAROUSEL_ALBUM", "REELS", "STORY" ] } }, "example": "IMAGE,VIDEO" } ], "responses": { "200": { "description": "Publishing behaviour series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "publishing_behaviour": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "likes": { "type": "integer", "example": 720 }, "comments": { "type": "integer", "example": 158 }, "saved": { "type": "integer", "example": 210 }, "engagement": { "type": "integer", "example": 1088 }, "reach": { "type": "integer", "example": 24000 }, "impressions": { "type": "integer", "example": 41000 }, "views": { "type": "integer", "example": 56000 }, "total_posts": { "type": "integer", "example": 4 } }, "type": "object" } }, "publishing_behaviour_rollup": { "description": "Per-media-type rollups for the current and previous periods.", "properties": { "current": { "type": "array", "items": { "type": "object" } }, "previous": { "type": "array", "items": { "type": "object" } } }, "type": "object", "example": { "current": [ { "media_type": "IMAGE", "total_posts": 14, "likes": 4200, "comments": 860, "saved": 1100, "engagement": 6160, "reach": 145000, "views": 180000 } ], "previous": [ { "media_type": "IMAGE", "total_posts": 11, "likes": 3600, "comments": 720, "saved": 940, "engagement": 5260, "reach": 125000, "views": 155000 } ] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/top-posts": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram top-performing posts", "operationId": "instagramAnalyticsTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "total_engagement", "post_engagement", "engagement", "like_count", "likes", "comments_count", "comments", "saved", "reach", "impressions", "views", "shares", "post_created_at", "published_at", "caption", "media_type" ], "example": "post_engagement" } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "IMAGE", "VIDEO", "CAROUSEL_ALBUM", "REELS", "STORY" ] } }, "example": "IMAGE,VIDEO" }, { "name": "entity_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "FEED", "REELS", "STORY" ] } }, "example": "FEED,REELS" } ], "responses": { "200": { "description": "Top posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "type": "object", "example": { "post_id": "17841400008460056", "platform_id": "17841400000001234", "caption": "New collection just dropped!", "media_type": "IMAGE", "entity_type": "FEED", "permalink": "https://www.instagram.com/p/abc123/", "like_count": 1240, "comment_count": 185, "saved": 320, "post_engagement": 1745, "reach": 28000, "impression_count": 42000, "views": 0, "share_count": 0, "day_of_week": "Friday", "hour_of_day": 18, "created_at": "2026-01-12T18:00:00Z", "published_at": "2026-01-12T13:00:00-05:00", "saved_at": "2026-01-12T18:05:00Z" } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/sorted-top-posts": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram top posts with hashtag filter", "operationId": "instagramAnalyticsGetTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "total_engagement", "post_engagement", "engagement", "like_count", "likes", "comments_count", "comments", "saved", "reach", "impressions", "views", "shares", "post_created_at", "published_at", "caption", "media_type" ], "example": "reach" } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "hashtags", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": "travel,food" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "IMAGE", "VIDEO", "CAROUSEL_ALBUM", "REELS", "STORY" ] } }, "example": "REELS" }, { "name": "entity_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "FEED", "REELS", "STORY" ] } }, "example": "REELS" } ], "responses": { "200": { "description": "Top posts retrieved successfully (same shape as /top-posts)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "description": "Same shape as /top-posts; filtered by hashtag/media_type.", "type": "array", "items": { "type": "object", "example": { "post_id": "17841400008460099", "platform_id": "17841400000001234", "caption": "Reel of the week 🎬", "media_type": "REELS", "entity_type": "REELS", "permalink": "https://www.instagram.com/reel/xyz789/", "like_count": 2100, "comment_count": 240, "saved": 410, "post_engagement": 2750, "reach": 52000, "impression_count": 78000, "views": 64000, "share_count": 320, "day_of_week": "Wednesday", "hour_of_day": 12, "created_at": "2026-01-14T12:00:00Z", "published_at": "2026-01-14T07:00:00-05:00", "saved_at": "2026-01-14T12:04:00Z" } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/post": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Get a single Instagram post by ID", "operationId": "instagramAnalyticsSinglePost", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "post_id", "in": "query", "description": "Platform-native identifier of the post.", "required": true, "schema": { "type": "string", "example": "17841400008460056" } } ], "responses": { "200": { "description": "Single post retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "post": { "description": "Same shape as a /top-posts item.", "type": "object", "example": { "post_id": "17841400008460056", "platform_id": "17841400000001234", "caption": "New collection just dropped!", "media_type": "IMAGE", "entity_type": "FEED", "permalink": "https://www.instagram.com/p/abc123/", "like_count": 1240, "comment_count": 185, "saved": 320, "post_engagement": 1745, "reach": 28000, "impression_count": 42000, "views": 0, "share_count": 0, "day_of_week": "Friday", "hour_of_day": 18, "created_at": "2026-01-12T18:00:00Z", "published_at": "2026-01-12T13:00:00-05:00", "saved_at": "2026-01-12T18:05:00Z" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/active-users": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram active users by hour and day of week", "operationId": "instagramAnalyticsActiveUsers", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Active users distribution retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "active_users_hours": { "properties": { "highest_value": { "type": "integer", "example": 5200 }, "highest_hour": { "type": "integer", "example": 19 }, "data": { "type": "array", "items": { "properties": { "hour": { "type": "integer", "example": 19 }, "value": { "type": "integer", "example": 5200 } }, "type": "object" } } }, "type": "object" }, "active_users_days": { "properties": { "highest_value": { "type": "integer", "example": 22000 }, "highest_day": { "type": "string", "example": "Saturday" }, "data": { "type": "array", "items": { "properties": { "day": { "type": "string", "example": "Saturday" }, "value": { "type": "integer", "example": 22000 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/impressions": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram post impressions over time", "operationId": "instagramAnalyticsImpressions", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Impressions series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "impressions": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "impressions": { "type": "integer", "example": 41000 } }, "type": "object" } }, "impressions_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "total_impressions": 92000, "avg_impressions": 2968 }, "previous": { "total_impressions": 84000, "avg_impressions": 2710 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/engagement": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram post engagement over time", "operationId": "instagramAnalyticsEngagement", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Engagement series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "engagements": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "engagement": { "type": "integer", "example": 1088 }, "comments": { "type": "integer", "example": 158 }, "reactions": { "type": "integer", "example": 720 }, "post_count": { "type": "integer", "example": 4 } }, "type": "object" } }, "engagements_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "engagement": 3600, "avg_engagement": 116.1, "comments": 580, "reactions": 2400, "saved": 720, "count": 24 }, "previous": { "engagement": 3200, "avg_engagement": 103.2, "comments": 510, "reactions": 2100, "saved": 640, "count": 20 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/hashtags": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram top hashtags by engagement", "operationId": "instagramAnalyticsHashtags", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Top hashtags retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_hashtags": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "#fashion" }, "engagement": { "type": "integer", "example": 3800 }, "likes": { "type": "integer", "example": 2800 }, "comments": { "type": "integer", "example": 480 }, "saved": { "type": "integer", "example": 520 }, "posts": { "type": "integer", "example": 12 } }, "type": "object" } }, "top_hashtags_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "post_engagement": 18500, "total_likes": 14200, "total_comments": 2400, "total_saves": 2800, "total_unique_hashtags": 38, "total_hashtag_uses": 112 }, "previous": { "post_engagement": 16200, "total_likes": 12400, "total_comments": 2100, "total_saves": 2450, "total_unique_hashtags": 32, "total_hashtag_uses": 95 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/stories-performance": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram stories impressions, reach, and interactions over time", "operationId": "instagramAnalyticsStoriesPerformance", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Stories performance series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "stories_performance": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "avg_story_impressions": { "type": "number", "example": 4500 }, "story_impressions": { "type": "integer", "example": 18000 }, "story_reach": { "type": "integer", "example": 13500 }, "story_reply": { "type": "integer", "example": 92 }, "story_exits": { "type": "integer", "example": 450 }, "story_taps_forward": { "type": "integer", "example": 1950 }, "story_taps_back": { "type": "integer", "example": 360 }, "published_stories": { "type": "integer", "example": 4 } }, "type": "object" } }, "stories_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "story_impressions": 185000, "avg_story_impressions": 4111, "story_reach": 138000, "story_reply": 950, "story_exits": 4800, "story_taps_forward": 21000, "story_taps_back": 3900, "published_stories": 45 }, "previous": { "story_impressions": 162000, "avg_story_impressions": 3789, "story_reach": 121000, "story_reply": 820, "story_exits": 4200, "story_taps_forward": 18500, "story_taps_back": 3400, "published_stories": 38 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/reels-performance": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram Reels engagement and watch time over time", "operationId": "instagramAnalyticsReelsPerformance", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Reels performance series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "reels": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "total_posts": { "type": "integer", "example": 3 }, "engagement": { "type": "integer", "example": 2100 }, "likes": { "type": "integer", "example": 1560 }, "comments": { "type": "integer", "example": 245 }, "saves": { "type": "integer", "example": 295 }, "shares": { "type": "integer", "example": 210 }, "avg_watch_time": { "type": "number", "example": 13.1 }, "total_watch_time": { "type": "integer", "example": 56000 } }, "type": "object" } }, "reels_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object", "example": { "current": { "engagement": 18500, "likes": 13800, "comments": 2200, "saves": 2800, "total_posts": 24, "shares": 1900, "avg_watch_time": 12.4, "total_watch_time": 425000 }, "previous": { "engagement": 16200, "likes": 12100, "comments": 1900, "saves": 2450, "total_posts": 20, "shares": 1650, "avg_watch_time": 11.8, "total_watch_time": 370000 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/demographics": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram audience age / gender breakdown", "operationId": "instagramAnalyticsDemographicsAge", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Audience age / gender retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "audience_age": { "type": "object", "example": { "13-17": 1250, "18-24": 9800, "25-34": 12400, "35-44": 7200, "45-54": 3100, "55-64": 1500, "65+": 550 } }, "audience_gender": { "type": "object", "example": { "female": 21500, "male": 13800, "unknown": 500 } }, "max_audience_age": { "properties": { "gender": { "type": "string", "example": "female" }, "age": { "type": "string", "example": "25-34" }, "value": { "type": "integer", "example": 7800 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/audience-location": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram audience country / city breakdown", "description": "Instagram reports top cities and top countries as two separate lists with nothing connecting them, so the country each city sits in is derived from the city label. Pass `country` to read one country's cities at a time; `available_countries` lists the codes that derivation placed at least one city in.", "operationId": "instagramAnalyticsCountryCity", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "country", "in": "query", "description": "Restrict `audience_city` to the cities attributed to one country (ISO 3166-1 alpha-2). Omit for the global city list. A country with no attributed cities returns an empty list rather than an error. `audience_country` and `available_countries` are unaffected.", "required": false, "schema": { "type": "string", "example": "PK" } } ], "responses": { "200": { "description": "Audience country / city retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "audience_city": { "description": "Followers by city, highest first. The label is the one Instagram reported, typically \"city, administrative division\".", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Islamabad, Islamabad Capital Territory" }, "value": { "type": "integer", "example": 4200 } }, "type": "object" } }, "audience_country": { "description": "Followers by ISO country code, highest first. Never affected by the `country` filter.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "PK" }, "value": { "type": "integer", "example": 16500 } }, "type": "object" } }, "available_countries": { "description": "Country codes accepted by `country`, ordered by follower count. Only countries with at least one attributed city appear.", "type": "array", "items": { "type": "string", "example": "PK" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/ai-insights": { "get": { "tags": [ "πŸ“Έ Instagram" ], "summary": "Instagram AI-generated insights", "description": "Two insight types over the same dataset, selected with `type`: `aiInsightsSummary` is a compact summary and `aiInsightsDetailed` is the full read-out. Generation is asynchronous: the first call returns a `generating` status, and repeating the same request returns the insight once it is ready. Results are cached for 24 hours, so a repeated call is normally immediate.", "operationId": "instagramAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "AI insights type key. `aiInsightsSummary` backs the Overview summary card and `aiInsightsDetailed` the AI Insights tab.", "required": true, "schema": { "type": "string", "default": "aiInsightsDetailed", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5 } }, { "name": "language", "in": "query", "description": "Response language (ISO 639-1)", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "AI insights retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "description": "AI-generated insight body, returned verbatim from the analytics service. The shape follows `type`: `aiInsightsSummary` returns `health_score`, `health_label`, `status_summary`, `summary_text` and exactly 3 `highlights`; `aiInsightsDetailed` returns `status_headline`, `status_reason`, `status_tone`, 3 `executive_summary` bullets, 6 `metrics`, `whats_happening` (an intro plus root-cause/effect/impact steps), 3-4 `actions` and 3 `suggested_prompts`. Every field is model-generated, so treat each as optional.", "type": "object", "example": { "success": true, "health_score": 78, "health_label": "Good", "status_summary": "Reels are winning", "summary_text": "Reels reached **2.1x** the accounts of static posts.", "highlights": [ "...", "...", "..." ], "confidence": "High" }, "additionalProperties": true }, "message": { "type": "string", "example": "", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/competitor/data-table-metrics": { "get": { "tags": [ "πŸ“Έ Instagram Competitors" ], "summary": "Per-competitor aggregate metrics table", "operationId": "instagramCompetitorDataTableMetrics", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/competitor/posting-activity-graph-by-types": { "get": { "tags": [ "πŸ“Έ Instagram Competitors" ], "summary": "Posting activity split by media type over time", "operationId": "instagramCompetitorPostingActivityGraphByTypes", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/competitor/posting-activity-by-specific-type": { "get": { "tags": [ "πŸ“Έ Instagram Competitors" ], "summary": "Posting activity for a specific media type", "operationId": "instagramCompetitorPostingActivityBySpecificType", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "description": "Comma-separated post-type filter.", "required": false, "schema": { "type": "string", "example": "photo,video" } }, { "$ref": "#/components/parameters/AnalyticsMediaProductType" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/competitor/top-and-least-performing-posts": { "get": { "tags": [ "πŸ“Έ Instagram Competitors" ], "summary": "Top and least performing competitor posts", "operationId": "instagramCompetitorTopAndLeastPerformingPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "sort_order", "in": "query", "description": "Sort direction for the ranked lists.", "required": false, "schema": { "type": "string", "example": "desc" } } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/competitor/top-hashtags": { "get": { "tags": [ "πŸ“Έ Instagram Competitors" ], "summary": "Most-used hashtags across IG competitors", "operationId": "instagramCompetitorTopHashtags", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/competitor/individual-hashtag-data": { "get": { "tags": [ "πŸ“Έ Instagram Competitors" ], "summary": "Posts for a specific competitor hashtag", "operationId": "instagramCompetitorIndividualHashtagData", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsHashtag" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/competitor/biography-data": { "get": { "tags": [ "πŸ“Έ Instagram Competitors" ], "summary": "Competitor profile bio and info", "operationId": "instagramCompetitorBiographyData", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/competitor/followers-growth-comparison": { "get": { "tags": [ "πŸ“Έ Instagram Competitors" ], "summary": "Follower growth comparison across IG competitors", "operationId": "instagramCompetitorFollowersGrowthComparison", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/instagram/competitor/posting-activity-table-by-type": { "get": { "tags": [ "πŸ“Έ Instagram Competitors" ], "summary": "Tabular breakdown of posting activity by type", "operationId": "instagramCompetitorPostingActivityTableByType", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsCompetitorReportId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "description": "Comma-separated post-type filter.", "required": false, "schema": { "type": "string", "example": "photo,video" } }, { "$ref": "#/components/parameters/AnalyticsMediaProductType" } ], "responses": { "200": { "description": "Retrieved successfully. Per-competitor rows carry `state`; a competitor with `state` other than `Processed` has no complete measurement for the period, and its metrics must not be read as zero.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/summary": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "LinkedIn summary KPIs β€” current vs previous period", "description": "`post_engagement` / `total_engagement`: Engagement counts reactions, comments, reposts and post clicks β€” the same components LinkedIn uses for `post_engagement_rate`, so counts and rates agree. `engagement_rate` and `post_engagement_rate` are percentages (engagement / impressions * 100); they previously returned a 0-1 ratio.", "operationId": "linkedinAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Page and post metrics broken into `current`, `previous`, absolute `difference`, and `percentage` change. Each block carries the same metric keys.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "followers": 12400, "page_views": 8200, "page_reach": 54000, "page_impressions": 72000, "page_unique_visitors": 6800, "page_reactions": 980, "page_shares": 340, "page_comments": 215, "engagement_rate": 4.2, "total_posts": 18, "post_likes": 3600, "post_comments": 480, "post_shares": 620, "post_clicks": 1950, "post_engagement": 6650, "post_engagement_rate": 3.8 }, "previous": { "followers": 11800, "page_views": 7600, "page_reach": 49000, "page_impressions": 66000, "page_unique_visitors": 6200, "page_reactions": 860, "page_shares": 295, "page_comments": 190, "engagement_rate": 3.9, "total_posts": 15, "post_likes": 3100, "post_comments": 420, "post_shares": 550, "post_clicks": 1720, "post_engagement": 5790, "post_engagement_rate": 3.5 }, "difference": { "followers": 600, "page_views": 600, "page_reach": 5000, "page_impressions": 6000, "page_unique_visitors": 600, "page_reactions": 120, "page_shares": 45, "page_comments": 25, "engagement_rate": 0.3, "total_posts": 3, "post_likes": 500, "post_comments": 60, "post_shares": 70, "post_clicks": 230, "post_engagement": 860, "post_engagement_rate": 0.3 }, "percentage": { "followers": 5.1, "page_views": 7.9, "page_reach": 10.2, "page_impressions": 9.1, "page_unique_visitors": 9.7, "page_reactions": 14, "page_shares": 15.3, "page_comments": 13.2, "engagement_rate": 7.7, "total_posts": 20, "post_likes": 16.1, "post_comments": 14.3, "post_shares": 12.7, "post_clicks": 13.4, "post_engagement": 14.8, "post_engagement_rate": 8.6 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/audience-growth": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "LinkedIn follower growth over time", "operationId": "linkedinAnalyticsAudienceGrowth", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Audience growth series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "audience_growth": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "organic_follower_count": { "type": "integer", "example": 12200 }, "organic_followers_daily": { "type": "integer", "example": 42 }, "paid_follower_count": { "type": "integer", "example": 200 }, "paid_followers_daily": { "type": "integer", "example": 3 }, "total_follower_count": { "type": "integer", "example": 12400 }, "total_followers_daily": { "type": "integer", "example": 45 } }, "type": "object" } }, "audience_growth_rollup": { "properties": { "current": { "properties": { "organic_follower_count": { "type": "integer", "example": 12200 }, "paid_follower_count": { "type": "integer", "example": 200 }, "total_follower_count": { "type": "integer", "example": 12400 }, "avg_follower_count": { "type": "number", "example": 12050 } }, "type": "object" }, "previous": { "properties": { "organic_follower_count": { "type": "integer", "example": 11600 }, "paid_follower_count": { "type": "integer", "example": 200 }, "total_follower_count": { "type": "integer", "example": 11800 }, "avg_follower_count": { "type": "number", "example": 11450 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/page-views": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "LinkedIn page views over time (desktop vs mobile)", "operationId": "linkedinAnalyticsPageViews", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Page views series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "page_views": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "desktop_page_views": { "type": "integer", "example": 520 }, "mobile_page_views": { "type": "integer", "example": 280 }, "total_page_views": { "type": "integer", "example": 800 }, "desktop_page_views_daily": { "type": "integer", "example": 520 }, "mobile_page_views_daily": { "type": "integer", "example": 280 }, "total_page_views_daily": { "type": "integer", "example": 800 } }, "type": "object" } }, "page_views_rollup": { "properties": { "current": { "properties": { "total_page_views": { "type": "integer", "example": 8200 }, "desktop_page_views": { "type": "integer", "example": 5100 }, "mobile_page_views": { "type": "integer", "example": 3100 }, "avg_page_views": { "type": "number", "example": 264.5 } }, "type": "object" }, "previous": { "properties": { "total_page_views": { "type": "integer", "example": 7600 }, "desktop_page_views": { "type": "integer", "example": 4700 }, "mobile_page_views": { "type": "integer", "example": 2900 }, "avg_page_views": { "type": "number", "example": 245.2 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/publishing-behaviour": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "LinkedIn post engagement by media type over time", "description": "`engagements`: Engagement counts reactions, comments, reposts and post clicks β€” the same components LinkedIn uses for `post_engagement_rate`, so counts and rates agree.", "operationId": "linkedinAnalyticsPublishingBehaviour", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "description": "Filter by media type (text, images, videos, carousel, link, documents)", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "text", "images", "videos", "carousel", "link", "documents" ] } }, "example": "images,videos" } ], "responses": { "200": { "description": "Publishing behaviour series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "publishing_behaviour": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "likes": { "type": "integer", "example": 420 }, "comments": { "type": "integer", "example": 85 }, "shares": { "type": "integer", "example": 120 }, "clicks": { "type": "integer", "example": 380 }, "engagement_rate": { "type": "number", "example": 3.8 }, "impressions": { "type": "integer", "example": 14500 }, "total_posts": { "type": "integer", "example": 3 }, "engagement": { "type": "integer", "example": 1005 }, "reach": { "type": "integer", "example": 11200 } }, "type": "object" } }, "publishing_behaviour_rollup": { "description": "Per-media-type rollups for the current and previous periods.", "properties": { "current": { "type": "array", "items": { "properties": { "media_type": { "type": "string", "example": "image" }, "total_posts": { "type": "integer", "example": 10 }, "likes": { "type": "integer", "example": 2400 }, "comments": { "type": "integer", "example": 480 }, "shares": { "type": "integer", "example": 680 }, "clicks": { "type": "integer", "example": 1800 }, "engagements": { "type": "integer", "example": 5360 }, "impressions": { "type": "integer", "example": 82000 }, "reach": { "type": "integer", "example": 63000 } }, "type": "object" } }, "previous": { "type": "array", "items": { "properties": { "media_type": { "type": "string", "example": "image" }, "total_posts": { "type": "integer", "example": 8 }, "likes": { "type": "integer", "example": 1900 }, "comments": { "type": "integer", "example": 360 }, "shares": { "type": "integer", "example": 510 }, "clicks": { "type": "integer", "example": 1400 }, "engagements": { "type": "integer", "example": 4170 }, "impressions": { "type": "integer", "example": 64000 }, "reach": { "type": "integer", "example": 48000 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/top-posts": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "LinkedIn top-performing posts", "description": "`post_engagement`: Engagement counts reactions, comments, reposts and post clicks β€” the same components LinkedIn uses for `post_engagement_rate`, so counts and rates agree. `order_by=engagement` and `order_by=post_engagement` rank by that count.", "operationId": "linkedinAnalyticsTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "default": "engagement", "enum": [ "engagement", "post_engagement", "total_engagement", "impressions", "reach", "comments", "favorites", "repost", "post_clicks", "created_at", "published_at", "caption", "title", "media_type" ] } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "text", "images", "videos", "carousel", "link", "poll" ] } }, "example": "images,videos" } ], "responses": { "200": { "description": "Top posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "type": "object", "example": { "platform_id": "urn:li:organization:123456", "post_id": "urn:li:share:7123456789", "activity": "urn:li:activity:7123456789", "media_type": "image", "article_url": "", "article_title": "", "post_data": "Excited to announce our Q1 results!", "thumbnail": "https://example.com/thumb.jpg", "media": [ "https://example.com/image.jpg" ], "type": "post", "hashtags": [ "#linkedin", "#growth" ], "comment_count": 48, "post_engagement": 1245, "like_count": 820, "title": "", "day_of_week": "Tuesday", "hour_of_day": 9, "created_at": "2026-01-14T09:00:00Z", "saved_at": "2026-01-14T09:05:00Z", "poll_data": "", "reach": 18500, "share_count": 215, "post_clicks": 460, "impression_count": 22000, "published_at": "2026-01-14T09:00:00Z" } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/sorted-top-posts": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "LinkedIn top posts with hashtag and media type filter", "operationId": "linkedinAnalyticsGetTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "engagement", "post_engagement", "total_engagement", "impressions", "reach", "comments", "favorites", "repost", "post_clicks", "created_at", "published_at", "caption", "title", "media_type" ], "example": "reach" } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "hashtags", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "example": "linkedin,growth" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "text", "images", "videos", "carousel", "link", "poll" ] } }, "example": "videos" } ], "responses": { "200": { "description": "Top posts retrieved successfully (same shape as /top-posts)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "description": "Same shape as /top-posts; filtered by hashtag/media_type.", "type": "array", "items": { "type": "object", "example": { "platform_id": "urn:li:organization:123456", "post_id": "urn:li:share:7987654321", "activity": "urn:li:activity:7987654321", "media_type": "video", "article_url": "", "article_title": "", "post_data": "Watch our latest product walkthrough.", "thumbnail": "https://example.com/thumb2.jpg", "media": [ "https://example.com/video.mp4" ], "type": "post", "hashtags": [ "#linkedin", "#product" ], "comment_count": 62, "post_engagement": 1820, "like_count": 1100, "title": "", "day_of_week": "Wednesday", "hour_of_day": 11, "created_at": "2026-01-21T11:00:00Z", "saved_at": "2026-01-21T11:04:00Z", "poll_data": "", "reach": 26000, "share_count": 310, "post_clicks": 590, "impression_count": 31000, "published_at": "2026-01-21T11:00:00Z" } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/post": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "Get a single LinkedIn post by ID", "operationId": "linkedinAnalyticsSinglePost", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "name": "post_id", "in": "query", "description": "Platform-native identifier of the post.", "required": true, "schema": { "type": "string", "example": "urn:li:share:7123456789" } } ], "responses": { "200": { "description": "Single post retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "post": { "description": "Same shape as a /top-posts item.", "type": "object", "example": { "platform_id": "urn:li:organization:123456", "post_id": "urn:li:share:7123456789", "activity": "urn:li:activity:7123456789", "media_type": "image", "article_url": "", "article_title": "", "post_data": "Excited to announce our Q1 results!", "thumbnail": "https://example.com/thumb.jpg", "media": [ "https://example.com/image.jpg" ], "type": "post", "hashtags": [ "#linkedin", "#growth" ], "comment_count": 48, "post_engagement": 1245, "like_count": 820, "title": "", "day_of_week": "Tuesday", "hour_of_day": 9, "created_at": "2026-01-14T09:00:00Z", "saved_at": "2026-01-14T09:05:00Z", "poll_data": "", "reach": 18500, "share_count": 215, "post_clicks": 460, "impression_count": 22000, "published_at": "2026-01-14T09:00:00Z" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/posts-per-days": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "LinkedIn post count distribution by day of week", "operationId": "linkedinAnalyticsPostsPerDays", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Posts per day distribution retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "posts_per_days": { "properties": { "data": { "properties": { "days": { "description": "Map of weekday name to post count.", "type": "object", "example": { "Monday": 4, "Tuesday": 6, "Wednesday": 5, "Thursday": 3, "Friday": 7, "Saturday": 1, "Sunday": 0 } }, "show_data": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/hashtags": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "LinkedIn top hashtags by engagement", "description": "`engagements` / `post_engagement`: Engagement counts reactions, comments, reposts and post clicks β€” the same components LinkedIn uses for `post_engagement_rate`, so counts and rates agree.", "operationId": "linkedinAnalyticsHashtags", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Top hashtags retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_hashtags": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "#linkedin" }, "engagements": { "type": "integer", "example": 2400 }, "likes": { "type": "integer", "example": 1600 }, "comments": { "type": "integer", "example": 280 }, "shares": { "type": "integer", "example": 360 }, "posts": { "type": "integer", "example": 8 } }, "type": "object" } }, "top_hashtags_rollup": { "properties": { "current": { "properties": { "total_hashtags": { "type": "integer", "example": 24 }, "total_times_used": { "type": "integer", "example": 68 }, "total_likes": { "type": "integer", "example": 9800 }, "total_comments": { "type": "integer", "example": 1420 }, "total_shares": { "type": "integer", "example": 2100 }, "post_engagement": { "type": "integer", "example": 13320 }, "total_impressions": { "type": "integer", "example": 124000 }, "total_reach": { "type": "integer", "example": 98000 } }, "type": "object" }, "previous": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/demographics": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "LinkedIn follower demographics by industry, country, and other dimensions", "operationId": "linkedinAnalyticsFollowersDemographics", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Follower demographics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "follower_demographics": { "description": "Map of demographic dimension (e.g. `industry`, `country`) to a bucket/values breakdown.", "type": "object", "example": { "industry": { "buckets": [ "Technology", "Marketing", "Finance" ], "values": [ 3800, 2100, 1400 ] }, "country": { "buckets": [ "US", "GB", "IN" ], "values": [ 4200, 1800, 1200 ] } }, "additionalProperties": { "type": "object", "@OA\\Property": [ { "property": "buckets", "type": "array", "@OA\\Items": { "type": "string" } }, { "property": "values", "type": "array", "@OA\\Items": { "type": "integer" } } ] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/linkedin/ai-insights": { "get": { "tags": [ "πŸ’Ό LinkedIn" ], "summary": "LinkedIn AI-generated insights", "description": "Two insight types over the same dataset, selected with `type`: `aiInsightsSummary` is a compact summary and `aiInsightsDetailed` is the full read-out. Generation is asynchronous: the first call returns a `generating` status, and repeating the same request returns the insight once it is ready. Results are cached for 24 hours, so a repeated call is normally immediate.", "operationId": "linkedinAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "AI insights type key. `aiInsightsSummary` backs the Overview summary card and `aiInsightsDetailed` the AI Insights tab.", "required": true, "schema": { "type": "string", "default": "aiInsightsDetailed", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5 } }, { "name": "language", "in": "query", "description": "Response language (ISO 639-1)", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "AI insights retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "description": "AI-generated insight body, returned verbatim from the analytics service. The shape follows `type`: `aiInsightsSummary` returns `health_score`, `health_label`, `status_summary`, `summary_text` and exactly 3 `highlights`; `aiInsightsDetailed` returns `status_headline`, `status_reason`, `status_tone`, 3 `executive_summary` bullets, 6 `metrics`, `whats_happening` (an intro plus root-cause/effect/impact steps), 3-4 `actions` and 3 `suggested_prompts`. Every field is model-generated, so treat each as optional.", "type": "object", "example": { "success": true, "health_score": 78, "health_label": "Good", "status_summary": "Reach surging", "summary_text": "Article posts reached **1.9x** the members of image posts.", "highlights": [ "...", "...", "..." ], "confidence": "High" }, "additionalProperties": true }, "message": { "type": "string", "example": "", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/accounts": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "List connected Meta ad accounts", "description": "The starting point for every other Meta Ads endpoint: it returns the `account_id` they all require, along with the account's currency. Only ad accounts the API key's owner may read are returned β€” a collaborator sees the accounts assigned to them and nothing else.", "operationId": "metaAdsAnalyticsAccounts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsSearch" } ], "responses": { "200": { "description": "Connected Meta ad accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsAccountsList" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/summary": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "Meta Ads headline KPIs β€” current vs previous period", "description": "Spend, reach, impressions, clicks, CPM, CPC and CTR for the requested range, each alongside the equivalent prior range and the absolute and percentage change. Monetary values are in currency.", "operationId": "metaAdsAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/MetaAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "currency": { "type": "string", "example": "USD" }, "account_id": { "type": "string", "example": "act_1234567890" }, "summary": { "description": "Four buckets carrying the same metric keys: `current`, `previous`, absolute `difference` and `percentage` change.", "type": "object", "example": { "current": { "spend": 4210.55, "reach": 98000, "impressions": 185000, "clicks": 3820, "cpm": 22.76, "cpc": 1.1, "ctr": 2.06 }, "previous": { "spend": 3890.1, "reach": 91000, "impressions": 168000, "clicks": 3410, "cpm": 23.15, "cpc": 1.14, "ctr": 2.03 }, "difference": { "spend": 320.45, "reach": 7000, "impressions": 17000, "clicks": 410, "cpm": -0.39, "cpc": -0.04, "ctr": 0.03 }, "percentage": { "spend": 8.2, "reach": 7.7, "impressions": 10.1, "clicks": 12, "cpm": -1.7, "cpc": -3.5, "ctr": 1.5 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/results-by-objective": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "Results and spend grouped by campaign objective", "description": "`results` means a different action per objective β€” reach for awareness, clicks for traffic, purchases for sales, and so on. See the metric glossary for the full mapping.", "operationId": "metaAdsAnalyticsResultsByObjective", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/MetaAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Results grouped by objective" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/performance-over-time": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "Daily time series for one or more metrics", "description": "Ask for several metrics at once with `metrics=spend,impressions,clicks` and they arrive under `series`, keyed by metric name β€” one request, one query, however many metrics. A single-metric request (`metric=spend`) returns the flat `performance_trend` array instead. Granularity is daily; it is the only granularity the ads data supports.", "operationId": "metaAdsAnalyticsPerformanceOverTime", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/MetaAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "metrics", "in": "query", "description": "Comma-separated metric list. Unknown names are ignored. When omitted, `metric` is used.", "required": false, "schema": { "type": "string", "example": "spend,impressions,clicks" } }, { "name": "metric", "in": "query", "description": "Single metric, used only when `metrics` is absent.", "required": false, "schema": { "type": "string", "default": "spend", "enum": [ "spend", "impressions", "reach", "clicks", "cpm", "cpc", "ctr", "frequency" ] } } ], "responses": { "200": { "description": "Time series retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "currency": { "type": "string", "example": "USD" }, "metric": { "type": "string", "example": "spend" }, "total": { "type": "number", "format": "float", "example": 4210.55 }, "performance_trend": { "type": "array", "items": { "$ref": "#/components/schemas/AdsTrendPoint" } }, "series": { "description": "Present only for a multi-metric request. Keyed by metric name.", "type": "object", "example": { "spend": [ { "date": "2026-08-01", "value": 412.55 } ], "clicks": [ { "date": "2026-08-01", "value": 322 } ] } }, "totals": { "description": "Range total per metric. Present only for a multi-metric request.", "type": "object", "example": { "spend": 4210.55, "clicks": 3820 } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/performance-by-level": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "One metric broken down by campaign, ad set or ad", "operationId": "metaAdsAnalyticsPerformanceByLevel", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/MetaAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "level", "in": "query", "required": false, "schema": { "type": "string", "default": "campaign", "enum": [ "campaign", "adset", "ad" ] } }, { "name": "metric", "in": "query", "required": false, "schema": { "type": "string", "default": "spend", "enum": [ "spend", "impressions", "reach", "clicks", "cpm", "cpc", "ctr", "frequency" ] } } ], "responses": { "200": { "description": "Breakdown retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/performance-by-placement": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "One metric broken down by publisher platform and placement", "description": "Where the ads actually ran β€” Facebook, Instagram, Audience Network, Messenger, and the device platform within each.", "operationId": "metaAdsAnalyticsPerformanceByPlacement", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/MetaAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "metric", "in": "query", "required": false, "schema": { "type": "string", "default": "spend", "enum": [ "spend", "impressions", "reach", "clicks", "cpm", "cpc", "ctr", "frequency" ] } } ], "responses": { "200": { "description": "Placement breakdown retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/campaigns": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "Campaigns with per-campaign metrics", "description": "Paginated with `limit`/`offset`. `total` is the number of campaigns matching the filters, so page through by advancing `offset` until it reaches `total`. Each response also returns `available_statuses` and `available_objectives`, which are the accepted values of the `status` and `objective` filters for this account and range.", "operationId": "metaAdsAnalyticsCampaigns", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/MetaAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsStatus" }, { "$ref": "#/components/parameters/AdsSearch" }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" }, { "name": "objective", "in": "query", "description": "Campaign objective filter. Accepted values are returned in `available_objectives`.", "required": false, "schema": { "type": "string", "example": "OUTCOME_SALES" } } ], "responses": { "200": { "description": "Campaigns retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "currency": { "type": "string", "example": "USD" }, "total": { "type": "integer", "example": 248 }, "limit": { "type": "integer", "example": 25 }, "offset": { "type": "integer", "example": 50 }, "available_statuses": { "type": "array", "items": { "type": "string" }, "example": [ "ACTIVE", "PAUSED" ] }, "available_objectives": { "type": "array", "items": { "type": "string" }, "example": [ "OUTCOME_SALES", "OUTCOME_TRAFFIC" ] }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/AdsTableRow" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/ad-sets": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "Ad sets with per-ad-set metrics", "description": "Pass `campaign_id` to drill into one campaign's ad sets; omit it for every ad set in the account.", "operationId": "metaAdsAnalyticsAdSets", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/MetaAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsCampaignId" }, { "$ref": "#/components/parameters/AdsStatus" }, { "$ref": "#/components/parameters/AdsSearch" }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" } ], "responses": { "200": { "description": "Ad sets retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "currency": { "type": "string", "example": "USD" }, "total": { "type": "integer", "example": 64 }, "limit": { "type": "integer", "example": 25 }, "offset": { "type": "integer", "example": 0 }, "ad_sets": { "type": "array", "items": { "$ref": "#/components/schemas/AdsTableRow" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/ads": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "Ads with per-ad metrics and creative details", "description": "Scope with `campaign_id`, `ad_set_id`, both, or neither. Rows include the creative's name, title, body and thumbnail URL.", "operationId": "metaAdsAnalyticsAds", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/MetaAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "$ref": "#/components/parameters/AdsCampaignId" }, { "name": "ad_set_id", "in": "query", "description": "Restrict results to a single ad set.", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AdsStatus" }, { "$ref": "#/components/parameters/AdsSearch" }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" } ], "responses": { "200": { "description": "Ads retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/demographics": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "Audience breakdown by age and gender, region or country", "description": "`breakdown=age_gender` returns the age/gender matrix under `by_age` and `by_gender`, each row a `{label, value, percent}` for the single selected `metric`. `breakdown=region` and `breakdown=country` return geographic rows under `demographics`, each carrying **all** metrics (spend, impressions, clicks, ctr) β€” so `metric` applies to the age/gender breakdown only and is ignored by the geographic ones. The region breakdown also returns `available_countries`; pass one back as `country` to narrow it.", "operationId": "metaAdsAnalyticsDemographics", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/MetaAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "breakdown", "in": "query", "required": false, "schema": { "type": "string", "default": "age_gender", "enum": [ "age_gender", "region", "country" ] } }, { "name": "country", "in": "query", "description": "ISO country code; narrows the `region` breakdown. Accepted values come back in that breakdown's `available_countries`.", "required": false, "schema": { "type": "string", "example": "PK" } }, { "name": "metric", "in": "query", "description": "Applies to `breakdown=age_gender` only. The geographic breakdowns return every metric per row and ignore this.", "required": false, "schema": { "type": "string", "default": "spend", "enum": [ "spend", "impressions", "reach", "clicks", "cpm", "cpc", "ctr", "frequency" ] } }, { "$ref": "#/components/parameters/AdsOrderBy" }, { "$ref": "#/components/parameters/AdsOrderDir" } ], "responses": { "200": { "description": "Demographic breakdown retrieved successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/meta-ads/ai-insights": { "get": { "tags": [ "♾️ Meta Ads" ], "summary": "AI-generated insights for an ad account", "description": "Two insight types over the same dataset, selected with `type`: `aiInsightsSummary` is a compact summary and `aiInsightsDetailed` is the full read-out. Generation is asynchronous: the first call returns a `generating` status, and repeating the same request returns the insight once it is ready. Results are cached for 24 hours, so a repeated call is normally immediate.", "operationId": "metaAdsAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/MetaAdsAccountId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "Which insight to generate.", "required": true, "schema": { "type": "string", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "language", "in": "query", "description": "Response language, ISO 639-1. Falls back to the request locale, then English.", "required": false, "schema": { "type": "string", "example": "en" } } ], "responses": { "200": { "description": "Either the generated insight, or an acknowledgement that generation is still running. Both are 200 β€” poll the same URL until status is true.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AdsAiInsightsGenerating" }, { "$ref": "#/components/schemas/AdsAiInsightsResult" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace or ad account permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/summary": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest summary KPIs β€” current vs previous period", "description": "`engagement_rate` is a percentage (pin clicks + outbound clicks + saves, over impressions * 100). It previously returned average engagement per pin, which is not a rate.", "operationId": "pinterestAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "board_id", "in": "query", "description": "Filter metrics to a specific board ID.", "required": false, "schema": { "type": "string", "example": "1234567890" } } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Account metrics broken into `current`, `previous`, absolute `difference`, and `percentage` change. Each block carries the same metric keys.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "follower_count": 12400, "post_engagement": 3800, "impressions": 94000, "pin_clicks": 2100, "outbound_clicks": 870, "saves": 1560 }, "previous": { "follower_count": 11800, "post_engagement": 3400, "impressions": 85000, "pin_clicks": 1900, "outbound_clicks": 780, "saves": 1380 }, "difference": { "follower_count": 600, "post_engagement": 400, "impressions": 9000, "pin_clicks": 200, "outbound_clicks": 90, "saves": 180 }, "percentage": { "follower_count": 5.1, "post_engagement": 11.8, "impressions": 10.6, "pin_clicks": 10.5, "outbound_clicks": 11.5, "saves": 13 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/audience-growth": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest cumulative follower trend over time", "operationId": "pinterestAnalyticsFollowerTrend", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Follower trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "aggregation_level": { "type": "string", "example": "day" }, "follower_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "followers_daily": { "type": "integer", "example": 12200 }, "followers_gained": { "type": "integer", "example": 42 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/audience-growth-daily": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest daily-delta follower trend", "operationId": "pinterestAnalyticsFollowerTrendDaily", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Daily follower trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "aggregation_level": { "type": "string", "example": "day" }, "follower_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "followers_daily": { "type": "integer", "example": 12200 }, "followers_gained": { "type": "integer", "example": 42 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/impressions": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest cumulative impressions trend over time", "operationId": "pinterestAnalyticsImpressionsTrend", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Impressions trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "aggregation_level": { "type": "string", "example": "day" }, "impressions_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "impressions_daily": { "type": "integer", "example": 3100 }, "impressions_total": { "type": "integer", "example": 94000 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/impressions-daily": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest daily-delta impressions trend", "operationId": "pinterestAnalyticsImpressionsTrendDaily", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Daily impressions trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "aggregation_level": { "type": "string", "example": "day" }, "impressions_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "impressions_daily": { "type": "integer", "example": 3100 }, "impressions_total": { "type": "integer", "example": 94000 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/engagement": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest cumulative engagement trend over time", "operationId": "pinterestAnalyticsEngagementTrend", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Engagement trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "aggregation_level": { "type": "string", "example": "day" }, "engagement_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "saves_daily": { "type": "integer", "example": 52 }, "saves_total": { "type": "integer", "example": 1560 }, "outbound_clicks_daily": { "type": "integer", "example": 29 }, "outbound_clicks_total": { "type": "integer", "example": 870 }, "pin_clicks_daily": { "type": "integer", "example": 70 }, "pin_clicks_total": { "type": "integer", "example": 2100 }, "engagement_daily": { "type": "integer", "example": 127 }, "engagement_total": { "type": "integer", "example": 3800 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/engagement-daily": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest daily-delta engagement trend", "operationId": "pinterestAnalyticsEngagementTrendDaily", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Daily engagement trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "aggregation_level": { "type": "string", "example": "day" }, "engagement_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "saves_daily": { "type": "integer", "example": 52 }, "saves_total": { "type": "integer", "example": 1560 }, "outbound_clicks_daily": { "type": "integer", "example": 29 }, "outbound_clicks_total": { "type": "integer", "example": 870 }, "pin_clicks_daily": { "type": "integer", "example": 70 }, "pin_clicks_total": { "type": "integer", "example": 2100 }, "engagement_daily": { "type": "integer", "example": 127 }, "engagement_total": { "type": "integer", "example": 3800 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/pin-posting": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest cumulative pin posting activity over time", "operationId": "pinterestAnalyticsPinPosting", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Pin posting activity retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "aggregation_level": { "type": "string", "example": "day" }, "pin_posting": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "pins_count": { "type": "integer", "example": 4 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/pin-posting-daily": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest daily-delta pin posting activity", "operationId": "pinterestAnalyticsPinPostingDaily", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Daily pin posting activity retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "aggregation_level": { "type": "string", "example": "day" }, "pin_posting": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "pins_count": { "type": "integer", "example": 4 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/pin-rollup": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest pin performance rollup β€” current vs previous period", "operationId": "pinterestAnalyticsPinRollup", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Pin rollup retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "overview": { "description": "Pin metrics broken into `current`, `previous`, absolute `difference`, and `percentage` change.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "total_pins": 48, "impressions": 94000, "pin_clicks": 2100, "outbound_clicks": 870, "saves": 1560, "quartile_95s_percent_view": 62.4, "video_views": 18000, "video_10s_view": 5400, "avg_watch_time": 14.2 }, "previous": { "total_pins": 42, "impressions": 85000, "pin_clicks": 1900, "outbound_clicks": 780, "saves": 1380, "quartile_95s_percent_view": 58.1, "video_views": 16200, "video_10s_view": 4800, "avg_watch_time": 13.6 }, "difference": { "total_pins": 6, "impressions": 9000, "pin_clicks": 200, "outbound_clicks": 90, "saves": 180, "quartile_95s_percent_view": 4.3, "video_views": 1800, "video_10s_view": 600, "avg_watch_time": 0.6 }, "percentage": { "total_pins": 14.3, "impressions": 10.6, "pin_clicks": 10.5, "outbound_clicks": 11.5, "saves": 13, "quartile_95s_percent_view": 7.4, "video_views": 11.1, "video_10s_view": 12.5, "avg_watch_time": 4.4 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/top-pins": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest top-performing and least-performing pins", "operationId": "pinterestAnalyticsTopPins", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "order_by", "in": "query", "description": "Sort field for both lists. Anything else falls back to total_engagement. Text columns (caption, board) sort alphabetically.", "required": false, "schema": { "type": "string", "default": "total_engagement", "enum": [ "impressions", "pin_clicks", "outbound_clicks", "saves", "total_engagement", "engagement_rate", "published_at", "created_at", "caption", "description", "title", "board", "board_name" ] } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": "IMAGE,VIDEO" } ], "responses": { "200": { "description": "Top pins retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top": { "type": "array", "items": { "type": "object", "example": { "post_id": "987654321098765432", "board_name": "Summer Recipes", "permalink": "https://www.pinterest.com/pin/987654321098765432/", "embed_link": "https://assets.pinterest.com/ext/embed.html?id=987654321098765432", "title": "5-Minute Avocado Toast", "description": "Quick and healthy breakfast idea.", "board_owner": "my_brand", "media_type": "IMAGE", "thumbnail": "https://i.pinimg.com/236x/ab/cd/ef.jpg", "dominant_color": "#e8d5b0", "creative_type": "REGULAR", "product_tags": [], "height": 500, "width": 400, "created_at": "2026-01-10T09:00:00Z", "published_at": "2026-01-10T04:00:00-05:00", "impression_count": 12400, "pin_clicks": 540, "outbound_clicks": 210, "saves": 380, "post_engagement": 1130, "engagement_rate": 9.1 } } }, "least": { "type": "array", "items": { "type": "object", "example": { "post_id": "987654321098700000", "board_name": "Summer Recipes", "permalink": "https://www.pinterest.com/pin/987654321098700000/", "embed_link": "https://assets.pinterest.com/ext/embed.html?id=987654321098700000", "title": "Plain Toast", "description": "A simple breakfast.", "board_owner": "my_brand", "media_type": "IMAGE", "thumbnail": "https://i.pinimg.com/236x/12/34/56.jpg", "dominant_color": "#cccccc", "creative_type": "REGULAR", "product_tags": [], "height": 500, "width": 400, "created_at": "2026-01-03T09:00:00Z", "published_at": "2026-01-03T04:00:00-05:00", "impression_count": 320, "pin_clicks": 8, "outbound_clicks": 3, "saves": 5, "post_engagement": 16, "engagement_rate": 0.5 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/pin": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Get a single Pinterest pin by ID", "operationId": "pinterestAnalyticsSinglePin", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "name": "post_id", "in": "query", "description": "Platform-native identifier of the pin.", "required": true, "schema": { "type": "string", "example": "987654321098765432" } } ], "responses": { "200": { "description": "Single pin retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "post": { "description": "Same shape as a /top-pins item.", "type": "object", "example": { "post_id": "987654321098765432", "board_name": "Summer Recipes", "permalink": "https://www.pinterest.com/pin/987654321098765432/", "embed_link": "https://assets.pinterest.com/ext/embed.html?id=987654321098765432", "title": "5-Minute Avocado Toast", "description": "Quick and healthy breakfast idea.", "board_owner": "my_brand", "media_type": "IMAGE", "thumbnail": "https://i.pinimg.com/236x/ab/cd/ef.jpg", "dominant_color": "#e8d5b0", "creative_type": "REGULAR", "product_tags": [], "height": 500, "width": 400, "created_at": "2026-01-10T09:00:00Z", "impression_count": 12400, "pin_clicks": 540, "outbound_clicks": 210, "saves": 380, "post_engagement": 1130, "engagement_rate": 9.1 } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/pin-performance": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest pin performance metrics over time", "operationId": "pinterestAnalyticsPinPerformance", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": "IMAGE,VIDEO" } ], "responses": { "200": { "description": "Pin performance retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "pin_performance": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "pins_count": { "type": "integer", "example": 4 }, "pin_clicks": { "type": "integer", "example": 70 }, "outbound_clicks": { "type": "integer", "example": 29 }, "saves": { "type": "integer", "example": 52 }, "engagements": { "type": "integer", "example": 127 }, "impressions": { "type": "integer", "example": 3100 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/pinterest/ai-insights": { "get": { "tags": [ "πŸ“Œ Pinterest" ], "summary": "Pinterest AI-generated insights", "description": "Two insight types over the same dataset, selected with `type`: `aiInsightsSummary` is a compact summary and `aiInsightsDetailed` is the full read-out. Generation is asynchronous: the first call returns a `generating` status, and repeating the same request returns the insight once it is ready. Results are cached for 24 hours, so a repeated call is normally immediate.", "operationId": "pinterestAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "AI insights type key. `aiInsightsSummary` backs the Overview summary card and `aiInsightsDetailed` the AI Insights tab.", "required": true, "schema": { "type": "string", "default": "aiInsightsDetailed", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5 } }, { "name": "language", "in": "query", "description": "Response language (ISO 639-1)", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "AI insights retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "description": "AI-generated insight body, returned verbatim from the analytics service. The shape follows `type`: `aiInsightsSummary` returns `health_score`, `health_label`, `status_summary`, `summary_text` and exactly 3 `highlights`; `aiInsightsDetailed` returns `status_headline`, `status_reason`, `status_tone`, 3 `executive_summary` bullets, 6 `metrics`, `whats_happening` (an intro plus root-cause/effect/impact steps), 3-4 `actions` and 3 `suggested_prompts`. Every field is model-generated, so treat each as optional.", "type": "object", "example": { "success": true, "health_score": 78, "health_label": "Good", "status_summary": "Saves are rising", "summary_text": "IMAGE pins earned **2.4x** the saves of VIDEO pins.", "highlights": [ "...", "...", "..." ], "confidence": "High" }, "additionalProperties": true }, "message": { "type": "string", "example": "", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/report-schedules": { "get": { "tags": [ "πŸ—“ Report Schedules" ], "summary": "List a workspace's report schedules", "operationId": "listAnalyticsReportSchedules", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "responses": { "200": { "description": "Schedules retrieved. `next_run_at` is when the next report will be built.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "report_schedules": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "66f0a1e660cb41530ca40d37" }, "name": { "type": "string", "example": "Monthly client report" }, "platform_type": { "type": "string", "example": "facebook" }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "day_of_week": { "description": "0-6, Sunday first. Weekly only.", "type": "integer", "nullable": true }, "day_of_month": { "description": "1-28. Monthly only.", "type": "integer", "nullable": true }, "time": { "type": "string", "example": "09:00", "nullable": true }, "timezone": { "type": "string", "example": "Europe/London", "nullable": true }, "next_run_at": { "type": "string", "nullable": true }, "email_list": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ—“ Report Schedules" ], "summary": "Create a report schedule", "description": "Sets a report to build automatically. day_of_month is capped at 28 so a monthly schedule also fires in February; day_of_week is 0-6 with 0 meaning Sunday.", "operationId": "createAnalyticsReportSchedule", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "platform_type", "frequency" ], "properties": { "name": { "type": "string" }, "platform_type": { "type": "string" }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "day_of_week": { "type": "integer", "maximum": 6, "minimum": 0 }, "day_of_month": { "type": "integer", "maximum": 28, "minimum": 1 }, "time": { "type": "string" }, "timezone": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "string" } }, "email_list": { "type": "array", "items": { "type": "string" } }, "callback_url": { "description": "POSTed after each run. Must be https.", "type": "string", "format": "uri" } }, "type": "object" }, "example": { "name": "Monthly client report", "platform_type": "facebook", "frequency": "monthly", "day_of_month": 1, "time": "09:00", "timezone": "Europe/London", "accounts": [ "1234567890" ], "email_list": [ "client@example.com" ], "callback_url": "https://example.com/hooks/report-ready" } } } }, "responses": { "201": { "description": "Schedule created", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/report-schedules/{schedule_id}": { "get": { "tags": [ "πŸ—“ Report Schedules" ], "summary": "Read one report schedule", "operationId": "getAnalyticsReportSchedule", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "200": { "description": "The schedule", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such schedule in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "πŸ—“ Report Schedules" ], "summary": "Update a report schedule", "operationId": "updateAnalyticsReportSchedule", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "name": "Monthly client report", "platform_type": "facebook", "frequency": "weekly", "day_of_week": 1 } } } }, "responses": { "200": { "description": "Schedule updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such schedule in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ—“ Report Schedules" ], "summary": "Delete a report schedule", "description": "Stops the recurring report. Reports already generated by it are not removed.", "operationId": "deleteAnalyticsReportSchedule", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such schedule in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/report-schedules/{schedule_id}/state": { "put": { "tags": [ "πŸ—“ Report Schedules" ], "summary": "Pause or resume a report schedule", "description": "A schedule auto-pauses after max_attempts consecutive failures - read `active`, `paused_reason` and `consecutive_failures` to see whether that has happened. Resuming clears the failure count so the schedule gets a full set of attempts again rather than pausing on the next single failure.", "operationId": "setAnalyticsReportScheduleState", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "active" ], "properties": { "active": { "type": "boolean" } }, "type": "object" }, "example": { "active": true } } } }, "responses": { "200": { "description": "State changed", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such schedule in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/report-schedules/{schedule_id}/run": { "post": { "tags": [ "πŸ—“ Report Schedules" ], "summary": "Run a schedule once, now", "description": "Builds and sends this schedule's report immediately, exactly as its next scheduled run would - same report, same recipients. Does NOT change the schedule: next_run_at is untouched and the regular run still happens. Asynchronous like every report, so this returns 202 and the report appears in the reports list.", "operationId": "runAnalyticsReportScheduleNow", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "202": { "description": "Run started", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such schedule in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/reports": { "get": { "tags": [ "πŸ“„ Analytics Reports" ], "summary": "List a workspace's generated reports", "operationId": "listAnalyticsReports", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "responses": { "200": { "description": "Reports retrieved. `status` distinguishes a report still being built from one ready to download; `export_url` is present only once it is.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "reports": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "66f0a1e660cb41530ca40d37" }, "name": { "type": "string", "example": "March client report" }, "platform_type": { "type": "string", "example": "facebook" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "progress": { "type": "integer", "example": 100 }, "export_url": { "description": "Null until the report is completed.", "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "scheduled", "manual", "export" ] }, "created_at": { "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“„ Analytics Reports" ], "summary": "Generate a report", "description": "Queues a report and returns its id immediately - the file is NOT ready when this call returns. Either read the report until status is completed, or pass callback_url to be POSTed once when it finishes. The callback is signed so the receiver can verify it came from ContentStudio.", "operationId": "generateAnalyticsReport", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "platform_type" ], "properties": { "name": { "type": "string" }, "platform_type": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "string" } }, "sections": { "description": "Which sections to include; omit for the full report. Read the valid values from the report-options endpoint - an unknown section is dropped silently.", "type": "array", "items": { "type": "string" } }, "date": { "type": "string" }, "timezone": { "type": "string" }, "callback_url": { "description": "POSTed once when the report finishes or fails. Must be https.", "type": "string", "format": "uri" } }, "type": "object" }, "example": { "name": "March client report", "platform_type": "facebook", "accounts": [ "1234567890" ], "date": "2026-03-01 - 2026-03-31", "timezone": "UTC", "callback_url": "https://example.com/hooks/report-ready" } } } }, "responses": { "202": { "description": "Accepted. 202 rather than 201 because the report does not exist as a file yet - only as a job.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "report": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/reports/options": { "get": { "tags": [ "πŸ“„ Analytics Reports" ], "summary": "What a report can be built from", "description": "The report types available and the sections each one can contain. Read this before generating rather than guessing section names: an unknown section is dropped silently, so the report builds and the section the caller wanted is simply absent.", "operationId": "listAnalyticsReportOptions", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "platform_type", "in": "query", "description": "Narrow the sections to one report type. Omit to get the catalogue for every type.", "required": false, "schema": { "type": "string", "example": "facebook" } } ], "responses": { "200": { "description": "Report types and their sections.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "report_types": { "description": "Values accepted as platform_type when generating.", "type": "array", "items": { "type": "string" } }, "sections": { "description": "Keyed by report type; each value is the sections that type can contain.", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "502": { "description": "Upstream analytics error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/reports/{report_id}": { "get": { "tags": [ "πŸ“„ Analytics Reports" ], "summary": "Read one report, including whether it is ready", "description": "This is the polling endpoint. Read it until `status` is `completed` and `export_url` is populated, or `failed`. A caller that would rather be told than ask should pass callback_url when generating.", "operationId": "getAnalyticsReport", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "200": { "description": "The report", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such report in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“„ Analytics Reports" ], "summary": "Delete a report", "operationId": "deleteAnalyticsReport", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such report in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/reports/{report_id}/retry": { "post": { "tags": [ "πŸ“„ Analytics Reports" ], "summary": "Retry a failed report", "operationId": "retryAnalyticsReport", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "202": { "description": "Retry queued", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such report in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/share-links": { "get": { "tags": [ "πŸ”— Analytics Share Links" ], "summary": "List a workspace's shareable analytics links", "operationId": "listAnalyticsShareLinks", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "responses": { "200": { "description": "Links retrieved. `password` is never included, whether or not a link has one.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "share_links": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "66f0a1e660cb41530ca40d37" }, "link_id": { "type": "string", "example": "a1b2c3d4e5" }, "share_url": { "type": "string", "example": "https://app.contentstudio.io/share/analytics/a1b2c3d4e5" }, "title": { "type": "string", "example": "Q1 Facebook Snapshot" }, "platform": { "type": "string", "example": "facebook" }, "account_id": { "type": "string", "nullable": true }, "is_password_protected": { "type": "boolean" }, "is_disabled": { "type": "boolean" }, "is_date_range_fixed": { "type": "boolean" }, "is_account_switching_enabled": { "description": "When true the viewer may switch accounts within the workspace, so the link is not confined to account_id.", "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ”— Analytics Share Links" ], "summary": "Create a shareable analytics link", "description": "Creates a link that anyone holding the URL can open without a ContentStudio account. It grants READ access to the workspace, platform and account it was created for, and nothing else. Set is_password_protected with a password to require one; the password is stored hashed and never returned.", "operationId": "createAnalyticsShareLink", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "platform" ], "properties": { "title": { "type": "string" }, "platform": { "type": "string", "enum": [ "overview", "facebook", "instagram", "linkedin", "tiktok", "youtube", "pinterest", "twitter", "gmb", "meta_ads", "google_ads" ] }, "account_id": { "type": "string", "nullable": true }, "overview_accounts": { "type": "array", "items": { "type": "string" }, "nullable": true }, "is_date_range_fixed": { "type": "boolean" }, "date_range": { "description": "Required when is_date_range_fixed is true. A fixed link keeps showing the period it was made for.", "type": "string", "nullable": true }, "is_account_switching_enabled": { "type": "boolean" }, "is_password_protected": { "type": "boolean" }, "password": { "description": "Write-only. Stored hashed, never returned.", "type": "string", "minLength": 4 }, "expires_at": { "description": "Optional deadline (date or datetime, must be in the future). After it passes the link stops opening and the viewer is told it expired. Omit for a link that lives until disabled or deleted.", "type": "string", "nullable": true } }, "type": "object" }, "example": { "title": "Q1 Facebook Snapshot", "platform": "facebook", "account_id": "1234567890", "is_date_range_fixed": true, "date_range": "2026-01-01 - 2026-03-31", "is_password_protected": true, "password": "sunflower" } } } }, "responses": { "201": { "description": "Created; the response carries share_url.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/share-links/{id}": { "get": { "tags": [ "πŸ”— Analytics Share Links" ], "summary": "Read one shareable analytics link", "operationId": "getAnalyticsShareLink", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "200": { "description": "The link. `password` is never included.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such link in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "πŸ”— Analytics Share Links" ], "summary": "Update a shareable analytics link", "operationId": "updateAnalyticsShareLink", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "platform" ], "properties": { "title": { "type": "string" }, "platform": { "type": "string", "enum": [ "overview", "facebook", "instagram", "linkedin", "tiktok", "youtube", "pinterest", "twitter", "gmb", "meta_ads", "google_ads" ] }, "account_id": { "type": "string", "nullable": true }, "overview_accounts": { "type": "array", "items": { "type": "string" }, "nullable": true }, "is_date_range_fixed": { "type": "boolean" }, "date_range": { "description": "Required when is_date_range_fixed is true. A fixed link keeps showing the period it was made for.", "type": "string", "nullable": true }, "is_account_switching_enabled": { "type": "boolean" }, "is_password_protected": { "type": "boolean" }, "password": { "description": "Write-only. Stored hashed, never returned.", "type": "string", "minLength": 4 }, "expires_at": { "description": "Optional deadline (date or datetime, must be in the future). After it passes the link stops opening and the viewer is told it expired. Omit for a link that lives until disabled or deleted.", "type": "string", "nullable": true } }, "type": "object" }, "example": { "title": "Q1 Facebook Snapshot (final)", "platform": "facebook", "is_password_protected": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such link in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ”— Analytics Share Links" ], "summary": "Delete a shareable analytics link", "description": "Takes effect immediately: the URL stops working for everyone holding it.", "operationId": "deleteAnalyticsShareLink", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No such link in this workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/summary": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads summary KPIs β€” current vs previous period", "description": "Post totals for the period alongside the account-level totals for the same days. The two sets are DIFFERENT MEASUREMENTS and will not match: `likes`/`replies`/`reposts`/`quotes` count interactions on posts PUBLISHED in the window, while `account_likes`/`account_replies`/`account_reposts`/`account_quotes` count interactions that happened in the window across every post the account has ever made. There is no impressions or reach figure because Threads publishes none; `profile_views` is profile views, not post impressions. `engagement_rate` is normalised by follower count, NOT impressions, so it is not comparable to the Facebook or LinkedIn engagement rate. `views` and `shares` are null when no post in the period reported them β€” Meta labels both post metrics 'in development' β€” and are excluded from every engagement total for that reason.", "operationId": "threadsAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Metrics broken into `current`, `previous`, absolute `difference` and `percentage` change.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "total_posts": 42, "likes": 1820, "replies": 310, "reposts": 240, "quotes": 55, "post_engagement": 2425, "engagement_rate": 0.41, "followers": 24310, "profile_views": 8940, "link_clicks": 612, "account_likes": 5120, "account_replies": 880, "account_reposts": 640, "account_quotes": 130, "posts_without_insights": 2, "views": null, "views_partial": false, "shares": null, "shares_partial": false }, "previous": { "total_posts": 38, "likes": 1610, "replies": 280, "reposts": 205, "quotes": 44, "post_engagement": 2139, "engagement_rate": 0.37, "followers": 23880, "profile_views": 8210, "link_clicks": 540, "account_likes": 4770, "account_replies": 810, "account_reposts": 590, "account_quotes": 118, "posts_without_insights": 1, "views": null, "views_partial": false, "shares": null, "shares_partial": false } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/audience-growth": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads follower trend, tracked since connection", "description": "Daily follower totals assembled from the snapshots ContentStudio retained. Meta's `followers_count` is point-in-time and ignores any date range, so there is no follower history before the first sync and none can be obtained later. Read `tracked` on every point: `tracked: true` is a measurement; `tracked: false` with a non-zero `followers_count` is a value legitimately carried forward from an earlier day; `tracked: false` with `followers_count: 0` is a day BEFORE tracking began and must be rendered as a gap, never as zero followers. `profile_views` is never carried forward β€” an untracked day has no measured views. The roll-up reports `followers_start` and `followers_end` as the first and last OBSERVED values, so `net_growth` goes negative for an account that lost followers.", "operationId": "threadsAnalyticsAudienceGrowth", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Follower trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "audience_growth": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-08-18" }, "followers_count": { "type": "integer", "example": 24310 }, "followers_daily": { "type": "integer", "example": 112 }, "profile_views": { "type": "integer", "example": 430 }, "tracked": { "description": "False for days with no retained snapshot. Combined with followers_count it distinguishes a measurement, a carried-forward value and an untracked gap.", "type": "boolean", "example": true } }, "type": "object" } }, "audience_growth_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/activity": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads account activity β€” the true per-day series", "description": "What happened on each day ACROSS THE WHOLE ACCOUNT: profile views, likes, replies, reposts, quotes and link clicks. This is the only genuinely per-day engagement measurement Threads offers, and it is deliberately separate from `engagement`, which buckets lifetime post counters by publish date. The two answer different questions and must not be plotted on one axis. Nothing here is carried forward β€” these are event counts, not levels β€” so read `tracked` to tell a day with no snapshot from a genuinely quiet one.", "operationId": "threadsAnalyticsActivity", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Account activity retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "activity": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-08-18" }, "profile_views": { "type": "integer", "example": 430 }, "likes": { "type": "integer", "example": 240 }, "replies": { "type": "integer", "example": 38 }, "reposts": { "type": "integer", "example": 27 }, "quotes": { "type": "integer", "example": 6 }, "link_clicks": { "type": "integer", "example": 41 }, "tracked": { "description": "False for days with no retained snapshot. An untracked day reads as zero and must be rendered as a gap.", "type": "boolean", "example": true } }, "type": "object" } }, "activity_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/engagement": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads engagement trend by post publish date", "description": "Engagement earned by the posts PUBLISHED on each day, measured at the last sync β€” not engagement that occurred on that day. Threads post counters are cumulative lifetime values, so a true daily interaction curve is not derivable from them; use `activity` for that. Accepts an optional comma-separated `media_type` filter using Meta's own vocabulary (TEXT_POST, IMAGE, VIDEO, CAROUSEL_ALBUM, AUDIO, REPOST_FACADE); values are matched case-insensitively.", "operationId": "threadsAnalyticsEngagement", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "description": "Comma-separated media types to include.", "required": false, "schema": { "type": "string", "example": "IMAGE,VIDEO" } } ], "responses": { "200": { "description": "Engagement trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "engagement": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-08-18" }, "likes": { "type": "integer", "example": 182 }, "replies": { "type": "integer", "example": 31 }, "reposts": { "type": "integer", "example": 24 }, "quotes": { "type": "integer", "example": 5 }, "total_posts": { "type": "integer", "example": 3 }, "engagement": { "type": "integer", "example": 242 }, "engagement_rate": { "type": "number", "format": "float", "example": 0.41 } }, "type": "object" } }, "engagement_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/publishing-behaviour": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads publishing behaviour and per-media-type breakdown", "description": "The same daily series as `engagement`, plus a roll-up per media type and a `total` row. Media types use Meta's own vocabulary and are stored verbatim, so a type Meta adds later appears as itself rather than as 'other'. REPOST_FACADE rows are reposts of other accounts' posts: Meta returns no insights for them at all, so they carry no engagement β€” that is 'not measured', not 'performed badly'. The total's engagement rate is post-weighted, not the mean of the per-type rates.", "operationId": "threadsAnalyticsPublishingBehaviour", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "description": "Comma-separated media types to include.", "required": false, "schema": { "type": "string", "example": "IMAGE,VIDEO" } } ], "responses": { "200": { "description": "Publishing behaviour retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "publishing_behaviour": { "type": "array", "items": { "type": "object" } }, "publishing_behaviour_rollup": { "properties": { "current": { "type": "array", "items": { "properties": { "media_type": { "type": "string", "example": "IMAGE" }, "total_posts": { "type": "integer", "example": 18 }, "likes": { "type": "integer", "example": 940 }, "replies": { "type": "integer", "example": 120 }, "reposts": { "type": "integer", "example": 88 }, "quotes": { "type": "integer", "example": 14 }, "total_engagement": { "type": "integer", "example": 1162 }, "engagement_rate": { "type": "number", "format": "float", "example": 0.48 } }, "type": "object" } }, "previous": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/top-posts": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads top posts for the period", "description": "Posts ranked by the requested metric, defaulting to total engagement. `insights_available: false` means Meta returned no insights for that post β€” always the case for a repost of another account's post β€” so its zeroes are 'not measured' rather than 'nobody engaged'. `view_count` and `reshare_count` are null when Meta did not report them; render a dash, not a 0. `media_url` and `thumbnail` are signed, EXPIRING CDN urls and must be re-read rather than cached indefinitely. A post with a `ghost_post_expires_at` is ephemeral by design and will disappear on schedule; that is not an error.", "operationId": "threadsAnalyticsTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "example": 5 } }, { "name": "order_by", "in": "query", "description": "engagement, engagement_rate, likes, replies, reposts, quotes, views, published_at or caption (post text, sorted alphabetically). Anything else falls back to engagement β€” there is no reach or impressions column to sort by.", "required": false, "schema": { "type": "string", "example": "engagement" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "media_type", "in": "query", "required": false, "schema": { "type": "string", "example": "IMAGE,VIDEO" } }, { "name": "hashtags", "in": "query", "description": "Comma-separated free-text hashtags the author typed.", "required": false, "schema": { "type": "string", "example": "marketing,launch" } }, { "name": "topic_tags", "in": "query", "description": "Comma-separated Threads topic tags. A separate filter from hashtags β€” a topic tag is curated by Meta, not written by the author.", "required": false, "schema": { "type": "string", "example": "Formula 1" } } ], "responses": { "200": { "description": "Top posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "properties": { "post_id": { "type": "string", "example": "17900000000000000" }, "permalink": { "type": "string", "example": "https://www.threads.net/@acct/post/Cxyz" }, "text": { "type": "string" }, "media_type": { "type": "string", "example": "IMAGE" }, "thumbnail": { "description": "Signed and expiring.", "type": "string" }, "topic_tag": { "type": "string", "example": "Formula 1" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "like_count": { "type": "integer", "example": 182 }, "reply_count": { "type": "integer", "example": 31 }, "share_count": { "description": "Reposts.", "type": "integer", "example": 24 }, "quote_count": { "type": "integer", "example": 5 }, "view_count": { "description": "Null when Meta did not report it β€” the metric is 'in development'.", "type": "integer", "nullable": true }, "reshare_count": { "description": "Null when Meta did not report it β€” the metric is 'in development'.", "type": "integer", "nullable": true }, "insights_available": { "type": "boolean", "example": true }, "post_engagement": { "type": "integer", "example": 242 }, "engagement_rate": { "type": "number", "format": "float", "example": 0.41 }, "published_at": { "type": "string", "example": "2026-08-18T09:15:00Z" }, "last_synced_at": { "description": "Counters are lifetime-to-date; this is when they were read.", "type": "string", "example": "2026-08-30T02:00:00Z" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/sorted-top-posts": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads posts, paged and sorted for a table view", "description": "The same rows as `top-posts` with a larger default page size (15) and an `offset` for paging. Use this for a table; use `top-posts` for a small ranked strip.", "operationId": "threadsAnalyticsSortedTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "example": 15 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "example": 0 } }, { "name": "order_by", "in": "query", "description": "Sort field. caption sorts the post text alphabetically; anything else falls back to engagement.", "required": false, "schema": { "type": "string", "default": "engagement", "enum": [ "engagement", "post_engagement", "total_engagement", "engagement_rate", "likes", "like_count", "replies", "reply_count", "comments", "reposts", "repost_count", "shares", "quotes", "quote_count", "views", "view_count", "published_at", "created_at", "caption", "text" ], "example": "engagement" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "media_type", "in": "query", "required": false, "schema": { "type": "string", "example": "IMAGE,VIDEO" } }, { "name": "hashtags", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "topic_tags", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/post": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "A single Threads post by media id", "description": "Looked up by identity: the post is resolved by `post_id`, so one published outside the dashboard window is still openable and the range never filters it out. The range is REQUIRED all the same β€” upstream validates it before it reads `post_id` β€” so it must be sent rather than omitted. `post_id` is the Threads media id.", "operationId": "threadsAnalyticsSinglePost", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "post_id", "in": "query", "description": "The Threads media id.", "required": true, "schema": { "type": "string", "example": "17900000000000000" } } ], "responses": { "200": { "description": "Post retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "post": { "description": "Same shape as a /top-posts item.", "properties": { "published_at": { "description": "Publish time in the requested `timezone` (RFC 3339 with its offset); null when unknown.", "type": "string", "format": "date-time", "example": "2026-01-22T09:08:00-05:00", "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/posts-per-days": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads posting cadence by weekday", "description": "How many posts were published on each weekday, bucketed in the requested timezone rather than UTC β€” 'what day did this go out' only means anything in the poster's own clock.", "operationId": "threadsAnalyticsPostsPerDays", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Posting cadence retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "posts_per_days": { "properties": { "data": { "properties": { "days": { "type": "object", "example": { "Monday": 6, "Tuesday": 4, "Wednesday": 7, "Thursday": 5, "Friday": 8, "Saturday": 2, "Sunday": 1 } }, "show_data": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/posts-per-hours": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads posting cadence by hour of day", "description": "A 24-element array indexed by hour, 00:00 to 23:00, bucketed in the requested timezone. An hour with no posts is 0 rather than absent, so the array index is always the hour.", "operationId": "threadsAnalyticsPostsPerHours", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Posting cadence retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "posts_per_hours": { "properties": { "data": { "properties": { "hours": { "type": "array", "items": { "type": "integer" } }, "show_data": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/hashtags": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads top hashtags β€” the tags the author typed", "description": "Free-text hashtags parsed from the post text, ranked by engagement. These are NOT Threads topic tags: a topic tag is one curated value Meta offers, and it has its own endpoint. `kind` on the response is 'hashtags' so a client rendering both in the same component cannot mislabel one as the other.", "operationId": "threadsAnalyticsHashtags", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Hashtags retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "kind": { "type": "string", "example": "hashtags" }, "top_hashtags": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "marketing" }, "engagements": { "type": "integer", "example": 412 }, "likes": { "type": "integer", "example": 310 }, "replies": { "type": "integer", "example": 52 }, "reposts": { "type": "integer", "example": 41 }, "quotes": { "type": "integer", "example": 9 }, "posts": { "type": "integer", "example": 7 } }, "type": "object" } }, "top_hashtags_rollup": { "properties": { "current": { "type": "object" }, "previous": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/topic-tags": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads top topic tags β€” Meta's curated concept", "description": "Threads topic tags ranked by engagement. A post carries at most ONE topic tag, chosen from a curated set rather than typed by the author, which is why this is a separate endpoint from `hashtags` and why `kind` on the response is 'topic_tags'. Presenting a topic tag as a hashtag would tell a customer they used a tag they never wrote.", "operationId": "threadsAnalyticsTopicTags", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Topic tags retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "kind": { "type": "string", "example": "topic_tags" }, "top_topic_tags": { "type": "array", "items": { "type": "object" } }, "top_topic_tags_rollup": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/demographics": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads follower demographics β€” age and gender", "description": "A POINT-IN-TIME breakdown of the audience, not a range aggregate. Meta ignores the date range for follower demographics entirely, so the response describes the audience as at `snapshot_date` β€” the newest snapshot at or before the end of the requested window. Summing or averaging across days would count the same follower once per snapshot. `percentage` is each bucket's share of the RETURNED buckets, not of the follower count. Meta requires at least 100 followers before it will return this at all; below that threshold the breakdown appears under `unavailable` with a reason, which is a normal state for a new account rather than an error. Pass `breakdown=country,city,age,gender` to override the default of age and gender.", "operationId": "threadsAnalyticsDemographics", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "breakdown", "in": "query", "description": "Comma-separated: country, city, age, gender.", "required": false, "schema": { "type": "string", "example": "age,gender" } }, { "name": "limit", "in": "query", "description": "Buckets per breakdown. Matters most for city, which has a long tail.", "required": false, "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "Demographics retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "demographics": { "properties": { "age": { "properties": { "breakdown": { "type": "string", "example": "age" }, "snapshot_date": { "description": "The day this composition was observed. It is not a range aggregate.", "type": "string", "example": "2026-08-29" }, "total": { "type": "integer", "example": 24310 }, "buckets": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "25-34" }, "value": { "type": "integer", "example": 9120 }, "percentage": { "type": "number", "format": "float", "example": 37.52 } }, "type": "object" } } }, "type": "object" } }, "type": "object" }, "unavailable": { "description": "Breakdown name to reason, when one could not be returned.", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/audience-location": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads follower demographics β€” country and city", "description": "The same point-in-time breakdown as `demographics`, defaulting to the geographic dimensions instead of age and gender. Every caveat there applies here, including the 100-follower threshold and `snapshot_date`. City has a long tail, so `limit` matters.", "operationId": "threadsAnalyticsAudienceLocation", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "breakdown", "in": "query", "required": false, "schema": { "type": "string", "example": "country,city" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "Audience location retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "demographics": { "type": "object" }, "unavailable": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/capabilities": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "What Threads analytics can and cannot answer", "description": "The authoritative, machine-readable list of which sections this platform serves and which metrics it cannot supply, each with a reason. Read this instead of hardcoding assumptions: it names impressions, reach, active users, stories, reels, competitor analytics, follower history, and the two 'in development' post metrics. `tracking` reports BOTH floors that can shorten a series β€” `tracked_since`, the first day ContentStudio holds a snapshot, and `platform_data_floor` (2024-04-13), before which Meta holds no account insights for anyone. `platform_data_guaranteed_from` (2024-06-01) is the date Meta begins warranting that data.", "operationId": "threadsAnalyticsCapabilities", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Capabilities retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "capabilities": { "properties": { "available": { "type": "array", "items": { "type": "string" } }, "unavailable": { "type": "array", "items": { "properties": { "metric": { "type": "string", "example": "impressions" }, "reason": { "type": "string", "example": "Threads publishes no impressions metric at post or account level. Profile views are a different measurement and are never reported as impressions." } }, "type": "object" } }, "notes": { "type": "array", "items": { "type": "string" } }, "tracking": { "properties": { "tracked_since": { "type": "string", "example": "2026-07-04" }, "snapshot_days": { "type": "integer", "example": 57 }, "trends_start_at_connection": { "type": "boolean", "example": true }, "platform_data_floor": { "type": "string", "example": "2024-04-13" }, "platform_data_guaranteed_from": { "type": "string", "example": "2024-06-01" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/threads/ai-insights": { "get": { "tags": [ "πŸ“Š Analytics: Threads" ], "summary": "Threads AI-generated insights", "description": "Two insight types over the same dataset, selected with `type`: `aiInsightsSummary` is a compact summary and `aiInsightsDetailed` is the full read-out. Generation is asynchronous: the first call returns a `generating` status, and repeating the same request returns the insight once it is ready. Results are cached for 24 hours, so a repeated call is normally immediate. The model is bound by the same limits the capabilities endpoint reports β€” it is instructed never to narrate impressions, reach, saves or video views for Threads, because the platform publishes none of them.", "operationId": "threadsAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "AI insights type key. `aiInsightsSummary` backs the Overview summary card and `aiInsightsDetailed` the AI Insights tab.", "required": true, "schema": { "type": "string", "default": "aiInsightsDetailed", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5 } }, { "name": "language", "in": "query", "description": "Response language (ISO 639-1)", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "AI insights retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "description": "AI-generated insight body, returned verbatim from the analytics service. The shape follows `type`: `aiInsightsSummary` returns `health_score`, `health_label`, `status_summary`, `summary_text` and exactly 3 `highlights`; `aiInsightsDetailed` returns `status_headline`, `status_reason`, `status_tone`, 3 `executive_summary` bullets, 6 `metrics`, `whats_happening` (an intro plus root-cause/effect/impact steps), 3-4 `actions` and 3 `suggested_prompts`. Every field is model-generated, so treat each as optional.", "type": "object", "example": { "success": true, "health_score": 74, "health_label": "Good", "status_summary": "Replies are climbing", "summary_text": "Text posts earned **1.8x** the replies of image posts.", "highlights": [ "...", "...", "..." ], "confidence": "High" }, "additionalProperties": true }, "message": { "type": "string", "example": "", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/tiktok/summary": { "get": { "tags": [ "🎡 TikTok" ], "summary": "TikTok summary KPIs β€” current vs previous period", "description": "`avg_engagement_rate` is a percentage (engagement / views * 100). It previously returned a 0-1 ratio cast to an integer, which reported 0 for most accounts.", "operationId": "tiktokAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Account and post metrics broken into `current`, `previous`, absolute `difference`, and `percentage` change. Each block carries the same metric keys.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "follower_count": 85000, "following_count": 320, "profile_views": 42000, "total_posts": 38, "post_engagement": 12400, "likes_count": 9800, "comments_count": 1400, "shares_count": 1200, "views_count": 520000 }, "previous": { "follower_count": 78000, "following_count": 305, "profile_views": 36000, "total_posts": 32, "post_engagement": 10800, "likes_count": 8500, "comments_count": 1200, "shares_count": 1100, "views_count": 460000 }, "difference": { "follower_count": 7000, "following_count": 15, "profile_views": 6000, "total_posts": 6, "post_engagement": 1600, "likes_count": 1300, "comments_count": 200, "shares_count": 100, "views_count": 60000 }, "percentage": { "follower_count": 9, "following_count": 4.9, "profile_views": 16.7, "total_posts": 18.8, "post_engagement": 14.8, "likes_count": 15.3, "comments_count": 16.7, "shares_count": 9.1, "views_count": 13 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/tiktok/audience-growth": { "get": { "tags": [ "🎡 TikTok" ], "summary": "TikTok follower and views trend over time", "operationId": "tiktokAnalyticsFollowerTrend", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Follower trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "follower_trend": { "type": "array", "items": { "properties": { "platform_id": { "type": "string", "example": "7012345678901234567" }, "display_name": { "type": "string", "example": "@mybrand" }, "logo": { "type": "string", "example": "https://example.com/logo.jpg" }, "followers_count": { "type": "array", "items": { "type": "integer" }, "example": [ 83000, 84200, 85000 ] }, "views_per_day": { "type": "array", "items": { "type": "integer" }, "example": [ 14000, 15200, 13800 ] }, "followers_count_diff": { "type": "array", "items": { "type": "integer" }, "example": [ 350, 420, 380 ] }, "views_per_day_diff": { "type": "array", "items": { "type": "integer" }, "example": [ -200, 1200, -1400 ] }, "day_bucket": { "type": "array", "items": { "type": "string" }, "example": [ "2026-01-29", "2026-01-30", "2026-01-31" ] } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/tiktok/publishing-behaviour": { "get": { "tags": [ "🎡 TikTok" ], "summary": "TikTok daily post volume and engagement breakdown over time", "operationId": "tiktokAnalyticsPublishingBehaviour", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Publishing behaviour retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "publishing_behaviour": { "type": "array", "items": { "properties": { "tiktok_id": { "type": "string", "example": "7012345678901234567" }, "page_name": { "type": "string", "example": "@mybrand" }, "logo": { "type": "string", "example": "https://example.com/logo.jpg" }, "days_bucket": { "type": "array", "items": { "type": "string" }, "example": [ "2026-01-29", "2026-01-30", "2026-01-31" ] }, "sum_view_count": { "type": "array", "items": { "type": "integer" }, "example": [ 14000, 15200, 13800 ] }, "sum_like_count": { "type": "array", "items": { "type": "integer" }, "example": [ 980, 1050, 920 ] }, "sum_comments_count": { "type": "array", "items": { "type": "integer" }, "example": [ 120, 140, 110 ] }, "sum_share_count": { "type": "array", "items": { "type": "integer" }, "example": [ 95, 110, 88 ] }, "sum_engagement_count": { "type": "array", "items": { "type": "integer" }, "example": [ 1195, 1300, 1118 ] }, "avg_engagement_rate": { "type": "array", "items": { "type": "number" }, "example": [ 1.4, 1.6, 1.3 ] }, "post_count": { "type": "array", "items": { "type": "integer" }, "example": [ 3, 4, 3 ] } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/tiktok/engagement": { "get": { "tags": [ "🎡 TikTok" ], "summary": "TikTok daily engagement trend over time", "operationId": "tiktokAnalyticsEngagementTrend", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Engagement trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "engagement_trend": { "type": "array", "items": { "properties": { "tiktok_id": { "type": "string", "example": "7012345678901234567" }, "page_name": { "type": "string", "example": "@mybrand" }, "logo": { "type": "string", "example": "https://example.com/logo.jpg" }, "total_video_likes": { "type": "array", "items": { "type": "integer" }, "example": [ 9800, 10200, 9600 ] }, "total_video_comments": { "type": "array", "items": { "type": "integer" }, "example": [ 1400, 1500, 1350 ] }, "total_video_shares": { "type": "array", "items": { "type": "integer" }, "example": [ 1200, 1300, 1150 ] }, "daily_video_likes": { "type": "array", "items": { "type": "integer" }, "example": [ 980, 1050, 920 ] }, "daily_video_comments": { "type": "array", "items": { "type": "integer" }, "example": [ 120, 140, 110 ] }, "daily_video_shares": { "type": "array", "items": { "type": "integer" }, "example": [ 95, 110, 88 ] }, "total_engagement": { "type": "array", "items": { "type": "integer" }, "example": [ 12400, 13000, 12100 ] }, "daily_engagement": { "type": "array", "items": { "type": "integer" }, "example": [ 1195, 1300, 1118 ] }, "days_bucket": { "type": "array", "items": { "type": "string" }, "example": [ "2026-01-29", "2026-01-30", "2026-01-31" ] } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/tiktok/top-posts": { "get": { "tags": [ "🎡 TikTok" ], "summary": "TikTok top and least performing posts", "operationId": "tiktokAnalyticsTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "sort_order", "in": "query", "description": "Sort metric for both the top and least lists.", "required": false, "schema": { "type": "string", "default": "engagement", "enum": [ "engagement", "total_engagement", "views", "views_count", "engagements_count", "likes_count", "comments_count", "shares_count", "created_time", "published_at" ] } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" } ], "responses": { "200": { "description": "Top posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "type": "object", "example": { "category": "video", "tiktok_id": "7012345678901234567", "page_name": "@mybrand", "logo": "https://example.com/logo.jpg", "profile_link": "https://www.tiktok.com/@mybrand", "post_id": "7198765432109876543", "cover_image_url": "https://example.com/cover.jpg", "share_url": "https://www.tiktok.com/@mybrand/video/7198765432109876543", "post_description": "Check out our latest product launch! #newproduct #brand", "hashtags": "#newproduct #brand", "duration": 45, "height": 1920, "width": 1080, "title": "New Product Launch", "embed_html": "", "embed_link": "https://www.tiktok.com/embed/v2/7198765432109876543", "likes_count": 4800, "comments_count": 620, "shares_count": 580, "views_count": 95000, "engagements_count": 6000, "engagement_count": 6000, "total_engagement": 6000, "engagement_rate": 7.06, "inserted_at": "2026-01-12T09:05:00Z", "created_time": "2026-01-12T09:00:00Z", "published_at": "2026-01-12T04:00:00-05:00", "total_follower_count": 85000, "total": 38 } } }, "least_posts": { "type": "array", "items": { "type": "object", "example": { "category": "video", "tiktok_id": "7012345678901234567", "page_name": "@mybrand", "logo": "https://example.com/logo.jpg", "profile_link": "https://www.tiktok.com/@mybrand", "post_id": "7198765432100000001", "cover_image_url": "https://example.com/cover2.jpg", "share_url": "https://www.tiktok.com/@mybrand/video/7198765432100000001", "post_description": "Quick tip of the day. #tips", "hashtags": "#tips", "duration": 12, "height": 1920, "width": 1080, "title": "Quick Tip", "embed_html": "", "embed_link": "https://www.tiktok.com/embed/v2/7198765432100000001", "likes_count": 120, "comments_count": 8, "shares_count": 4, "views_count": 2400, "engagements_count": 132, "engagement_count": 132, "total_engagement": 132, "engagement_rate": 0.72, "inserted_at": "2026-01-05T09:05:00Z", "created_time": "2026-01-05T09:00:00Z", "published_at": "2026-01-05T04:00:00-05:00", "total_follower_count": 85000, "total": 38 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/tiktok/post": { "get": { "tags": [ "🎡 TikTok" ], "summary": "Get a single TikTok post by ID", "operationId": "tiktokAnalyticsSinglePost", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "name": "post_id", "in": "query", "description": "Platform-native identifier of the post.", "required": true, "schema": { "type": "string", "example": "7198765432109876543" } } ], "responses": { "200": { "description": "Single post retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "post": { "description": "Same shape as a /top-posts item.", "type": "object", "example": { "category": "video", "tiktok_id": "7012345678901234567", "page_name": "@mybrand", "logo": "https://example.com/logo.jpg", "profile_link": "https://www.tiktok.com/@mybrand", "post_id": "7198765432109876543", "cover_image_url": "https://example.com/cover.jpg", "share_url": "https://www.tiktok.com/@mybrand/video/7198765432109876543", "post_description": "Check out our latest product launch! #newproduct #brand", "hashtags": "#newproduct #brand", "duration": 45, "height": 1920, "width": 1080, "title": "New Product Launch", "embed_html": "", "embed_link": "https://www.tiktok.com/embed/v2/7198765432109876543", "likes_count": 4800, "comments_count": 620, "shares_count": 580, "views_count": 95000, "engagements_count": 6000, "engagement_count": 6000, "total_engagement": 6000, "engagement_rate": 7.06, "inserted_at": "2026-01-12T09:05:00Z", "created_time": "2026-01-12T09:00:00Z", "total_follower_count": 85000, "total": 38 } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/tiktok/sorted-top-posts": { "get": { "tags": [ "🎡 TikTok" ], "summary": "TikTok posts sorted by a configurable metric", "operationId": "tiktokAnalyticsSortedTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "default": "engagement", "enum": [ "engagement", "total_engagement", "engagements_count", "likes_count", "comments_count", "shares_count", "views", "views_count", "created_time", "published_at", "caption" ] } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" } ], "responses": { "200": { "description": "Sorted posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "sorted_post": { "type": "array", "items": { "type": "object", "example": { "category": "video", "tiktok_id": "7012345678901234567", "page_name": "@mybrand", "logo": "https://example.com/logo.jpg", "profile_link": "https://www.tiktok.com/@mybrand", "post_id": "7198765432109876543", "cover_image_url": "https://example.com/cover.jpg", "share_url": "https://www.tiktok.com/@mybrand/video/7198765432109876543", "post_description": "Check out our latest product launch! #newproduct #brand", "hashtags": "#newproduct #brand", "duration": 45, "height": 1920, "width": 1080, "title": "New Product Launch", "embed_html": "", "embed_link": "https://www.tiktok.com/embed/v2/7198765432109876543", "likes_count": 4800, "comments_count": 620, "shares_count": 580, "views_count": 95000, "engagements_count": 6000, "engagement_count": 6000, "total_engagement": 6000, "engagement_rate": 7.06, "inserted_at": "2026-01-12T09:05:00Z", "created_time": "2026-01-12T09:00:00Z", "published_at": "2026-01-12T04:00:00-05:00", "total_follower_count": 85000, "total": 38 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/tiktok/ai-insights": { "get": { "tags": [ "🎡 TikTok" ], "summary": "TikTok AI-generated insights", "description": "Two insight types over the same dataset, selected with `type`: `aiInsightsSummary` is a compact summary and `aiInsightsDetailed` is the full read-out. Generation is asynchronous: the first call returns a `generating` status, and repeating the same request returns the insight once it is ready. Results are cached for 24 hours, so a repeated call is normally immediate.", "operationId": "tiktokAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "AI insights type key. `aiInsightsSummary` backs the Overview summary card and `aiInsightsDetailed` the AI Insights tab.", "required": true, "schema": { "type": "string", "default": "aiInsightsDetailed", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5 } }, { "name": "language", "in": "query", "description": "Response language (ISO 639-1)", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "AI insights retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "description": "AI-generated insight body, returned verbatim from the analytics service. The shape follows `type`: `aiInsightsSummary` returns `health_score`, `health_label`, `status_summary`, `summary_text` and exactly 3 `highlights`; `aiInsightsDetailed` returns `status_headline`, `status_reason`, `status_tone`, 3 `executive_summary` bullets, 6 `metrics`, `whats_happening` (an intro plus root-cause/effect/impact steps), 3-4 `actions` and 3 `suggested_prompts`. Every field is model-generated, so treat each as optional.", "type": "object", "example": { "success": true, "health_score": 78, "health_label": "Good", "status_summary": "Short videos win", "summary_text": "Videos under **30s** held **2.4x** the watch time of longer clips.", "highlights": [ "...", "...", "..." ], "confidence": "High" }, "additionalProperties": true }, "message": { "type": "string", "example": "", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/twitter/summary": { "get": { "tags": [ "βœ–οΈ X/Twitter" ], "summary": "Twitter summary KPIs β€” current vs previous period", "operationId": "twitterAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Account metrics broken into `current`, `previous`, absolute `difference`, and `percentage` change. Each block carries the same metric keys.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "follower_count": 12400, "following_count": 850, "total_posts": 42, "post_engagement": 3200, "impression_count": 84000, "like_count": 2100, "retweet_count": 480, "reply_count": 360, "quote_count": 260, "bookmark_count": 180 }, "previous": { "follower_count": 11800, "following_count": 840, "total_posts": 38, "post_engagement": 2900, "impression_count": 76000, "like_count": 1900, "retweet_count": 430, "reply_count": 320, "quote_count": 235, "bookmark_count": 160 }, "difference": { "follower_count": 600, "following_count": 10, "total_posts": 4, "post_engagement": 300, "impression_count": 8000, "like_count": 200, "retweet_count": 50, "reply_count": 40, "quote_count": 25, "bookmark_count": 20 }, "percentage": { "follower_count": 5.1, "following_count": 1.2, "total_posts": 10.5, "post_engagement": 10.3, "impression_count": 10.5, "like_count": 10.5, "retweet_count": 11.6, "reply_count": 12.5, "quote_count": 10.6, "bookmark_count": 12.5 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/twitter/engagement-impression": { "get": { "tags": [ "βœ–οΈ X/Twitter" ], "summary": "Twitter engagement and impression trend over time", "operationId": "twitterAnalyticsEngagementImpression", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Engagement and impression trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "twitter_id": { "type": "string", "example": "987654321" }, "engagement_impression": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "tweet_count": { "type": "integer", "example": 3 }, "impression_count": { "type": "integer", "example": 2800 }, "post_engagement": { "type": "integer", "example": 320 }, "retweet_count": { "type": "integer", "example": 48 }, "reply_count": { "type": "integer", "example": 36 }, "like_count": { "type": "integer", "example": 210 }, "bookmark_count": { "type": "integer", "example": 18 }, "quote_count": { "type": "integer", "example": 28 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/twitter/audience-growth": { "get": { "tags": [ "βœ–οΈ X/Twitter" ], "summary": "Twitter follower trend over time", "operationId": "twitterAnalyticsFollowersTrend", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Followers trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "platform_id": { "type": "string", "example": "987654321" }, "name": { "type": "string", "example": "ContentStudio" }, "username": { "type": "string", "example": "contentstudio_io" }, "follower_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "follower_count": { "type": "integer", "example": 12400 }, "follower_count_daily": { "type": "integer", "example": 22 }, "following_count": { "type": "integer", "example": 850 }, "following_count_daily": { "type": "integer", "example": 1 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/twitter/top-tweets": { "get": { "tags": [ "βœ–οΈ X/Twitter" ], "summary": "Twitter top-performing tweets", "operationId": "twitterAnalyticsTopTweets", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "default": "post_engagement", "enum": [ "total_engagement", "post_engagement", "like_count", "reply_count", "quote_count", "retweet_count", "impression_count", "bookmark_count", "published_at", "tweeted_at", "created_at", "caption", "tweet_text" ] } }, { "name": "sort_order", "in": "query", "description": "Sort direction. Anything other than `asc` is treated as `desc`.", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "tweet_type", "in": "query", "description": "Comma-separated tweet types forwarded to upstream verbatim.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": "tweet,retweet" } ], "responses": { "200": { "description": "Top tweets retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_tweets": { "type": "array", "items": { "type": "object", "example": { "post_id": "1748291234567890123", "created_at": "2026-01-15T14:30:00Z", "published_at": "2026-01-15T09:30:00-05:00", "tweet_text": "Excited to announce our new analytics dashboard! πŸš€ #ContentStudio", "tweet_type": "tweet", "permalink": "https://twitter.com/contentstudio_io/status/1748291234567890123", "media_url": [], "listed_count": 42, "share_count": 95, "like_count": 480, "comment_count": 62, "quote_count": 38, "bookmark_count": 55, "impression_count": 12400, "post_engagement": 730 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/twitter/tweet": { "get": { "tags": [ "βœ–οΈ X/Twitter" ], "summary": "Get a single Twitter/X tweet by ID", "operationId": "twitterAnalyticsSingleTweet", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "post_id", "in": "query", "description": "Platform-native identifier of the tweet.", "required": true, "schema": { "type": "string", "example": "1748291234567890123" } } ], "responses": { "200": { "description": "Single tweet retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "tweet": { "description": "Same shape as a /top-tweets item.", "type": "object", "example": { "post_id": "1748291234567890123", "created_at": "2026-01-15T14:30:00Z", "published_at": "2026-01-15T09:30:00-05:00", "tweet_text": "Excited to announce our new analytics dashboard! πŸš€ #ContentStudio", "tweet_type": "tweet", "permalink": "https://twitter.com/contentstudio_io/status/1748291234567890123", "media_url": [], "listed_count": 42, "share_count": 95, "like_count": 480, "comment_count": 62, "quote_count": 38, "bookmark_count": 55, "impression_count": 12400, "post_engagement": 730 } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/twitter/credits-used": { "get": { "tags": [ "βœ–οΈ X/Twitter" ], "summary": "Twitter API credits usage for the workspace", "operationId": "twitterAnalyticsCreditsUsed", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Credits usage retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "credits": { "properties": { "credits_used": { "type": "integer", "example": 1500000 }, "start_date": { "type": "string", "example": "2026-01-01" }, "end_date": { "type": "string", "example": "2026-01-31" }, "workspace_id": { "type": "string", "example": "610a1e660cb41530ca40d372" }, "twitter_id": { "type": "string", "example": "987654321" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/twitter/ai-insights": { "get": { "tags": [ "βœ–οΈ X/Twitter" ], "summary": "X (Twitter) AI insights", "operationId": "twitterAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "AI insights type key. `aiInsightsSummary` backs the Overview summary card and `aiInsightsDetailed` the AI Insights tab.", "required": true, "schema": { "type": "string", "default": "aiInsightsDetailed", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "language", "in": "query", "description": "Response language (ISO 639-1)", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "AI insights retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "description": "AI-generated insight body, returned verbatim from the analytics service. Generation is asynchronous: a cache miss answers with `status: generating` and the client re-requests when signalled, while `success: false` with `message` of `insufficient data` is a terminal answer for an account with no tweets in range. The readout metrics are computed server-side from the same summary the Overview cards use, so the two cannot disagree β€” Posts, Engagement, Impressions, Likes, Retweets, Replies and Followers. There is no reach metric: X takes no unique-reach measurement. Every model-generated field should be treated as optional.", "type": "object", "example": { "success": true, "health_score": 72, "health_label": "Good", "status_headline": "Impressions climbing on shorter posts", "confidence": "Medium" }, "additionalProperties": true }, "message": { "type": "string", "example": "", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/analytics/workspace-reports/options": { "get": { "tags": [ "🏒 Workspace Reports" ], "summary": "List the workspaces available for a cross-workspace report", "description": "What the caller may combine. A workspace absent from this list cannot be included, and naming it in generate will not produce an error - it will simply not appear in the report.", "operationId": "listWorkspaceReportOptions", "responses": { "200": { "description": "Available workspaces", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/analytics/workspace-reports": { "get": { "tags": [ "🏒 Workspace Reports" ], "summary": "List the caller's cross-workspace reports", "operationId": "listWorkspaceReports", "responses": { "200": { "description": "Reports retrieved", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "🏒 Workspace Reports" ], "summary": "Generate a cross-workspace report", "description": "Asynchronous, like every report: returns 202 and a report id. The response also names the workspaces actually included, which may be fewer than requested if the caller lacks access to some - read that back rather than assuming every id you sent was covered.", "operationId": "generateWorkspaceReport", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "date", "workspace_ids" ], "properties": { "title": { "type": "string" }, "date": { "type": "string" }, "workspace_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "widgets": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string" }, "timezone": { "type": "string" } }, "type": "object" }, "example": { "title": "All clients β€” March", "date": "2026-03-01 - 2026-03-31", "workspace_ids": [ "610a1e660cb41530ca40d372", "610a1e660cb41530ca40d373" ], "timezone": "UTC" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "None of the requested workspaces are accessible", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/analytics/workspace-reports/{report_id}": { "get": { "tags": [ "🏒 Workspace Reports" ], "summary": "Read one cross-workspace report, including whether it is ready", "operationId": "getWorkspaceReport", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "200": { "description": "The report", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not the caller's report", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "🏒 Workspace Reports" ], "summary": "Delete a cross-workspace report", "operationId": "deleteWorkspaceReport", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not the caller's report", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/summary": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube summary KPIs β€” current vs previous period", "operationId": "youtubeAnalyticsSummary", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Summary KPIs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "summary": { "description": "Channel metrics broken into `current`, `previous`, absolute `difference`, and `percentage` change. Each block carries the same metric keys.", "properties": { "current": { "type": "object" }, "previous": { "type": "object" }, "difference": { "type": "object" }, "percentage": { "type": "object" } }, "type": "object", "example": { "current": { "subscribers": 48200, "videos": 185, "views": 125000, "watch_time": 385000, "avg_view_duration": 184.2, "like": 4200, "dislike": 85, "comment": 620, "share": 380, "engagement": 5285 }, "previous": { "subscribers": 45800, "videos": 178, "views": 112000, "watch_time": 345000, "avg_view_duration": 178.6, "like": 3800, "dislike": 75, "comment": 560, "share": 340, "engagement": 4775 }, "difference": { "subscribers": 2400, "videos": 7, "views": 13000, "watch_time": 40000, "avg_view_duration": 5.6, "like": 400, "dislike": 10, "comment": 60, "share": 40, "engagement": 510 }, "percentage": { "subscribers": 5.2, "videos": 3.9, "views": 11.6, "watch_time": 11.6, "avg_view_duration": 3.1, "like": 10.5, "dislike": 13.3, "comment": 10.7, "share": 11.8, "engagement": 10.7 } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/audience-growth": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube cumulative subscriber trend over time", "operationId": "youtubeAnalyticsSubscriberTrend", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Subscriber trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "subscriber_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "subscribers_gained_daily": { "type": "integer", "example": 85 }, "subscribers_total": { "type": "integer", "example": 47027 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/audience-growth-daily": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube daily-delta subscriber trend", "operationId": "youtubeAnalyticsSubscriberTrendDaily", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Daily subscriber trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "subscriber_trend_daily": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "subscribers_gained_daily": { "type": "integer", "example": 85 }, "subscribers_total": { "type": "integer", "example": 47027 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/engagement": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube cumulative engagement trend over time", "operationId": "youtubeAnalyticsEngagementTrend", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Engagement trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "engagement_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "like_daily": { "type": "integer", "example": 158 }, "like_total": { "type": "integer", "example": 41358 }, "dislike_daily": { "type": "integer", "example": 2 }, "dislike_total": { "type": "integer", "example": 822 }, "share_daily": { "type": "integer", "example": 14 }, "share_total": { "type": "integer", "example": 3614 }, "comment_daily": { "type": "integer", "example": 24 }, "comment_total": { "type": "integer", "example": 5924 }, "engagement_daily": { "type": "integer", "example": 198 }, "engagement_total": { "type": "integer", "example": 51718 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/engagement-daily": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube daily-delta engagement trend", "operationId": "youtubeAnalyticsEngagementTrendDaily", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Daily engagement trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "engagement_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "like_daily": { "type": "integer", "example": 158 }, "like_total": { "type": "integer", "example": 41358 }, "dislike_daily": { "type": "integer", "example": 2 }, "dislike_total": { "type": "integer", "example": 822 }, "share_daily": { "type": "integer", "example": 14 }, "share_total": { "type": "integer", "example": 3614 }, "comment_daily": { "type": "integer", "example": 24 }, "comment_total": { "type": "integer", "example": 5924 }, "engagement_daily": { "type": "integer", "example": 198 }, "engagement_total": { "type": "integer", "example": 51718 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/views-trend": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube cumulative views split by subscriber / non-subscriber", "operationId": "youtubeAnalyticsViewsTrend", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Views trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "views_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "subscriber_views_daily": { "type": "integer", "example": 3100 }, "subscriber_views_total": { "type": "integer", "example": 88100 }, "non_subscriber_views_daily": { "type": "integer", "example": 1600 }, "non_subscriber_views_total": { "type": "integer", "example": 43600 }, "video_views_daily": { "type": "integer", "example": 4700 }, "video_views_total": { "type": "integer", "example": 131700 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/views-trend-daily": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube daily-delta views trend", "operationId": "youtubeAnalyticsViewsTrendDaily", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Daily views trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "views_trend": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "subscriber_views_daily": { "type": "integer", "example": 3100 }, "subscriber_views_total": { "type": "integer", "example": 88100 }, "non_subscriber_views_daily": { "type": "integer", "example": 1600 }, "non_subscriber_views_total": { "type": "integer", "example": 43600 }, "video_views_daily": { "type": "integer", "example": 4700 }, "video_views_total": { "type": "integer", "example": 131700 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/watch-time-trend": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube cumulative watch time split by subscriber / non-subscriber", "operationId": "youtubeAnalyticsWatchTimeTrend", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Watch time trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "watch_time": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "subscriber_watch_time_daily": { "type": "integer", "example": 9300 }, "subscriber_watch_time_total": { "type": "integer", "example": 261300 }, "non_subscriber_watch_time_daily": { "type": "integer", "example": 4800 }, "non_subscriber_watch_time_total": { "type": "integer", "example": 130800 }, "average_watch_time": { "type": "number", "example": 188.6 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/watch-time-trend-daily": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube daily-delta watch time trend", "operationId": "youtubeAnalyticsWatchTimeTrendDaily", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Daily watch time trend retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "watch_time": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "subscriber_watch_time_daily": { "type": "integer", "example": 9300 }, "subscriber_watch_time_total": { "type": "integer", "example": 261300 }, "non_subscriber_watch_time_daily": { "type": "integer", "example": 4800 }, "non_subscriber_watch_time_total": { "type": "integer", "example": 130800 }, "average_watch_time": { "type": "number", "example": 188.6 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/find-video": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube traffic source breakdown (how viewers found videos)", "operationId": "youtubeAnalyticsFindVideo", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Traffic source breakdown retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "find_video": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "YouTube Search" }, "value": { "type": "integer", "example": 68000 }, "perc_value": { "type": "number", "example": 54.4 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/video-sharing": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube sharing platform breakdown", "operationId": "youtubeAnalyticsVideoSharing", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Sharing breakdown retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "video_sharing": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Copy Link" }, "value": { "type": "integer", "example": 180 }, "perc_value": { "type": "number", "example": 47.4 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/publishing-behaviour": { "get": { "tags": [ "▢️ YouTube" ], "summary": "Publishing behaviour breakdown by content type", "description": "How many videos of each content type were published in the range and how they performed. YouTube stores only `video` and `short`; a trailing `total` row carries the column-wise sum. Only types with videos in the range appear. `watch_time` is already in minutes.", "operationId": "youtubeAnalyticsPublishingBehaviour", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsDateRange" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "video", "short" ] } }, "example": "short" } ], "responses": { "200": { "description": "Publishing behaviour breakdown retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "publishing_behaviour_breakdown": { "description": "Keyed by period: `current` for the requested range, `previous` for the equivalent prior range.", "properties": { "current": { "type": "array", "items": { "type": "object" } }, "previous": { "type": "array", "items": { "type": "object" } } }, "type": "object", "example": { "current": [ { "media_type": "short", "total_videos": 26, "engagement": 4200, "likes": 3600, "comments": 240, "shares": 360, "views": 182000, "watch_time": 9400 }, { "media_type": "video", "total_videos": 11, "engagement": 1850, "likes": 1490, "comments": 180, "shares": 180, "views": 74000, "watch_time": 21500 }, { "media_type": "total", "total_videos": 37, "engagement": 6050, "likes": 5090, "comments": 420, "shares": 540, "views": 256000, "watch_time": 30900 } ], "previous": [] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/demographics": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube audience demographics β€” age & gender, device type, subscriber change", "operationId": "youtubeAnalyticsDemographics", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Demographics retrieved successfully. Empty sections return empty arrays / zeroed subscribers rather than an error.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "age_gender": { "type": "array", "items": { "properties": { "age_group": { "type": "string", "example": "age25-34" }, "gender": { "type": "string", "example": "female" }, "perc_value": { "type": "number", "example": 22.5 } }, "type": "object" } }, "device_type": { "description": "Device types pre-sorted per metric. Each key holds an array of {name, value(=views), watch_time}.", "properties": { "views": { "type": "array", "items": { "type": "object" } }, "watch_time": { "type": "array", "items": { "type": "object" } } }, "type": "object", "example": { "views": [ { "name": "TV", "value": 350879, "watch_time": 164860 } ], "watch_time": [ { "name": "TV", "value": 350879, "watch_time": 164860 } ] } }, "subscribers": { "properties": { "gained": { "type": "integer", "example": 298 }, "lost": { "type": "integer", "example": 154 }, "net": { "type": "integer", "example": 144 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/top-geographies": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube top geographies β€” countries pre-sorted by views, watch time, view duration and view percentage", "operationId": "youtubeAnalyticsTopGeographies", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Top geographies retrieved successfully. Empty lists are returned rather than an error.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_geographies": { "description": "Top countries pre-sorted per metric. Each key holds an array of {name, value(=views), watch_time, avg_view_duration, avg_view_percentage}.", "properties": { "views": { "type": "array", "items": { "type": "object" } }, "watch_time": { "type": "array", "items": { "type": "object" } }, "view_duration": { "type": "array", "items": { "type": "object" } }, "view_percentage": { "type": "array", "items": { "type": "object" } } }, "type": "object", "example": { "views": [ { "name": "NZ", "value": 7939, "watch_time": 21106, "avg_view_duration": 159.4, "avg_view_percentage": 41.2 } ], "watch_time": [ { "name": "NZ", "value": 7939, "watch_time": 21106, "avg_view_duration": 159.4, "avg_view_percentage": 41.2 } ], "view_duration": [ { "name": "GB", "value": 969, "watch_time": 1899, "avg_view_duration": 201.3, "avg_view_percentage": 52.1 } ], "view_percentage": [ { "name": "GB", "value": 969, "watch_time": 1899, "avg_view_duration": 201.3, "avg_view_percentage": 52.1 } ] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/top-posts": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube top videos ordered by views and engagement", "description": "Video metrics come from two YouTube APIs. `impression_count` (views), `like_count`, `comment_count` and `favorites` are lifetime Data API counts. `average_view_duration` (seconds), `average_view_percentage`, `share_count`, `minutes_watched`, `red_minutes_watched`, `red_views`, `subscribers_gained` and `dislike_count` come from the YouTube Analytics API and cover the requested date range only. `duration` is the video length in whole seconds. `engagement_rate` is `post_engagement / impression_count * 100`. `favorites` is always 0 (deprecated by YouTube). Videos are selected by publish date falling inside the range, so a video published earlier is not returned however many views it received during the range. Unique viewers are not available from the YouTube API and are therefore not returned.", "operationId": "youtubeAnalyticsTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "video", "short" ] } }, "example": "video,short" } ], "responses": { "200": { "description": "Top videos retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts_ordered_by_views": { "type": "array", "items": { "type": "object", "example": { "platform_id": "UCxxxxxxxxxxxxxx", "post_id": "dQw4w9WgXcQ", "title": "2026 Product Overview", "description": "A complete walkthrough of all new features released in 2026.", "duration": 742, "thumbnail": "https://example.com/thumb.jpg", "media_type": "video", "iframe_embed_url": "https://www.youtube.com/embed/dQw4w9WgXcQ", "share_url": "https://youtu.be/dQw4w9WgXcQ", "post_engagement": 5285, "like_count": 4200, "dislike_count": 85, "impression_count": 125000, "red_views": 1200, "favorites": 0, "comment_count": 620, "subscribers_gained": 78, "share_count": 380, "minutes_watched": 6418, "red_minutes_watched": 180, "average_view_duration": 184.2, "average_view_percentage": 74.8, "engagement_rate": 4.23, "created_at": "2026-01-08T15:00:00Z", "published_at": "2026-01-08T10:00:00-05:00" } } }, "top_posts_ordered_by_engagement": { "type": "array", "items": { "type": "object", "example": { "platform_id": "UCxxxxxxxxxxxxxx", "post_id": "abc123xyz", "title": "How We Grew 10x in 2025", "description": "The full growth playbook, step by step.", "duration": 905, "thumbnail": "https://example.com/thumb2.jpg", "media_type": "video", "iframe_embed_url": "https://www.youtube.com/embed/abc123xyz", "share_url": "https://youtu.be/abc123xyz", "post_engagement": 7160, "like_count": 5800, "dislike_count": 60, "impression_count": 98000, "red_views": 1400, "favorites": 0, "comment_count": 840, "subscribers_gained": 132, "share_count": 520, "minutes_watched": 7120, "red_minutes_watched": 210, "average_view_duration": 201.4, "average_view_percentage": 78.2, "engagement_rate": 7.31, "created_at": "2026-01-15T12:00:00Z", "published_at": "2026-01-15T07:00:00-05:00" } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/least-posts": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube least-performing videos ordered by views and engagement", "description": "Video metrics come from two YouTube APIs. `impression_count` (views), `like_count`, `comment_count` and `favorites` are lifetime Data API counts. `average_view_duration` (seconds), `average_view_percentage`, `share_count`, `minutes_watched`, `red_minutes_watched`, `red_views`, `subscribers_gained` and `dislike_count` come from the YouTube Analytics API and cover the requested date range only. `duration` is the video length in whole seconds. `engagement_rate` is `post_engagement / impression_count * 100`. `favorites` is always 0 (deprecated by YouTube). Videos are selected by publish date falling inside the range, so a video published earlier is not returned however many views it received during the range. Unique viewers are not available from the YouTube API and are therefore not returned.", "operationId": "youtubeAnalyticsLeastPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "video", "short" ] } }, "example": "video,short" } ], "responses": { "200": { "description": "Least-performing videos retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "least_posts_ordered_by_views": { "type": "array", "items": { "type": "object", "example": { "platform_id": "UCxxxxxxxxxxxxxx", "post_id": "zzz000", "title": "Behind the Scenes Clip", "description": "", "duration": 48, "thumbnail": "https://example.com/thumb3.jpg", "media_type": "short", "iframe_embed_url": "https://www.youtube.com/embed/zzz000", "share_url": "https://youtu.be/zzz000", "post_engagement": 55, "like_count": 42, "dislike_count": 1, "impression_count": 850, "red_views": 20, "favorites": 0, "comment_count": 8, "subscribers_gained": 2, "share_count": 5, "minutes_watched": 180, "red_minutes_watched": 6, "average_view_duration": 22.4, "average_view_percentage": 46.7, "engagement_rate": 6.47, "created_at": "2026-01-28T09:00:00Z", "published_at": "2026-01-28T04:00:00-05:00" } } }, "least_posts_ordered_by_engagement": { "type": "array", "items": { "type": "object", "example": { "platform_id": "UCxxxxxxxxxxxxxx", "post_id": "zzz001", "title": "Quick Update", "description": "", "duration": 30, "thumbnail": "https://example.com/thumb4.jpg", "media_type": "short", "iframe_embed_url": "https://www.youtube.com/embed/zzz001", "share_url": "https://youtu.be/zzz001", "post_engagement": 35, "like_count": 28, "dislike_count": 1, "impression_count": 620, "red_views": 12, "favorites": 0, "comment_count": 4, "subscribers_gained": 1, "share_count": 3, "minutes_watched": 95, "red_minutes_watched": 4, "average_view_duration": 18.1, "average_view_percentage": 38.4, "engagement_rate": 5.65, "created_at": "2026-01-30T11:00:00Z", "published_at": "2026-01-30T06:00:00-05:00" } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/sorted-top-posts": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube videos sorted by a configurable metric", "description": "Video metrics come from two YouTube APIs. `impression_count` (views), `like_count`, `comment_count` and `favorites` are lifetime Data API counts. `average_view_duration` (seconds), `average_view_percentage`, `share_count`, `minutes_watched`, `red_minutes_watched`, `red_views`, `subscribers_gained` and `dislike_count` come from the YouTube Analytics API and cover the requested date range only. `duration` is the video length in whole seconds. `engagement_rate` is `post_engagement / impression_count * 100`. `favorites` is always 0 (deprecated by YouTube). Videos are selected by publish date falling inside the range, so a video published earlier is not returned however many views it received during the range. Unique viewers are not available from the YouTube API and are therefore not returned.", "operationId": "youtubeAnalyticsSortedTopPosts", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "$ref": "#/components/parameters/AnalyticsLimit" }, { "$ref": "#/components/parameters/AnalyticsOffset" }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string", "default": "engagement", "enum": [ "views", "likes", "dislikes", "engagement", "comments", "shares", "engagement_rate", "minutes_watched", "published_at", "average_view_duration", "subscribers_gained", "caption", "description", "title" ] } }, { "$ref": "#/components/parameters/AnalyticsOrderDirection" }, { "name": "media_type", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "video", "short" ] } }, "example": "video" } ], "responses": { "200": { "description": "Sorted videos retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "top_posts": { "type": "array", "items": { "type": "object", "example": { "platform_id": "UCxxxxxxxxxxxxxx", "post_id": "dQw4w9WgXcQ", "title": "2026 Product Overview", "description": "A complete walkthrough of all new features released in 2026.", "duration": 742, "thumbnail": "https://example.com/thumb.jpg", "media_type": "video", "iframe_embed_url": "https://www.youtube.com/embed/dQw4w9WgXcQ", "share_url": "https://youtu.be/dQw4w9WgXcQ", "post_engagement": 5285, "like_count": 4200, "dislike_count": 85, "impression_count": 125000, "red_views": 1200, "favorites": 0, "comment_count": 620, "subscribers_gained": 78, "share_count": 380, "minutes_watched": 6418, "red_minutes_watched": 180, "average_view_duration": 184.2, "average_view_percentage": 74.8, "engagement_rate": 4.23, "created_at": "2026-01-08T15:00:00Z", "published_at": "2026-01-08T10:00:00-05:00" } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/video": { "get": { "tags": [ "▢️ YouTube" ], "summary": "Get a single YouTube video by ID", "description": "Video metrics come from two YouTube APIs. `impression_count` (views), `like_count`, `comment_count` and `favorites` are lifetime Data API counts. `average_view_duration` (seconds), `average_view_percentage`, `share_count`, `minutes_watched`, `red_minutes_watched`, `red_views`, `subscribers_gained` and `dislike_count` come from the YouTube Analytics API and cover the requested date range only. `duration` is the video length in whole seconds. `engagement_rate` is `post_engagement / impression_count * 100`. `favorites` is always 0 (deprecated by YouTube). This endpoint selects the video by `post_id` and accepts no date range, so the Analytics API fields are the most recently stored values for that video. Unique viewers are not available from the YouTube API and are therefore not returned.", "operationId": "youtubeAnalyticsSingleVideo", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "post_id", "in": "query", "description": "Platform-native identifier of the video.", "required": true, "schema": { "type": "string", "example": "dQw4w9WgXcQ" } } ], "responses": { "200": { "description": "Single video retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "post": { "description": "Same shape as a /top-posts video item.", "type": "object", "example": { "platform_id": "UCxxxxxxxxxxxxxx", "post_id": "dQw4w9WgXcQ", "title": "2026 Product Overview β€” What's New", "description": "A complete walkthrough of all new features released in 2026.", "duration": 742, "thumbnail": "https://example.com/thumb.jpg", "media_type": "video", "iframe_embed_url": "https://www.youtube.com/embed/dQw4w9WgXcQ", "share_url": "https://youtu.be/dQw4w9WgXcQ", "post_engagement": 5285, "like_count": 4200, "dislike_count": 85, "impression_count": 125000, "red_views": 1200, "favorites": 0, "comment_count": 620, "subscribers_gained": 78, "share_count": 380, "minutes_watched": 6418, "red_minutes_watched": 180, "average_view_duration": 184.2, "average_view_percentage": 74.8, "engagement_rate": 4.23, "created_at": "2026-01-08T15:00:00Z", "published_at": "2026-01-08T10:00:00-05:00" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/performance-schedule": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube video performance metrics grouped by publish date", "operationId": "youtubeAnalyticsPerformanceSchedule", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" } ], "responses": { "200": { "description": "Performance schedule retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "engagement": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "count": { "type": "integer", "example": 3 }, "likes": { "type": "integer", "example": 420 }, "dislikes": { "type": "integer", "example": 9 }, "shares": { "type": "integer", "example": 38 }, "comments": { "type": "integer", "example": 64 }, "engagement": { "type": "integer", "example": 531 } }, "type": "object" } }, "video_views": { "type": "array", "items": { "properties": { "date": { "type": "string", "example": "2026-01-31" }, "count": { "type": "integer", "example": 3 }, "subscriber_views": { "type": "integer", "example": 3100 }, "non_subscriber_views": { "type": "integer", "example": 1600 } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/analytics/youtube/ai-insights": { "get": { "tags": [ "▢️ YouTube" ], "summary": "YouTube AI-generated insights", "description": "Two insight types over the same dataset, selected with `type`: `aiInsightsSummary` is a compact summary and `aiInsightsDetailed` is the full read-out. Generation is asynchronous: the first call returns a `generating` status, and repeating the same request returns the insight once it is ready. Results are cached for 24 hours, so a repeated call is normally immediate.", "operationId": "youtubeAnalyticsAiInsights", "parameters": [ { "$ref": "#/components/parameters/AnalyticsWorkspaceId" }, { "$ref": "#/components/parameters/AnalyticsPlatformId" }, { "$ref": "#/components/parameters/AnalyticsStartDate" }, { "$ref": "#/components/parameters/AnalyticsEndDate" }, { "$ref": "#/components/parameters/AnalyticsTimezone" }, { "name": "type", "in": "query", "description": "AI insights type key. `aiInsightsSummary` backs the Overview summary card and `aiInsightsDetailed` the AI Insights tab.", "required": true, "schema": { "type": "string", "default": "aiInsightsDetailed", "enum": [ "aiInsightsSummary", "aiInsightsDetailed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 5 } }, { "name": "language", "in": "query", "description": "Response language (ISO 639-1)", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "AI insights retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "data": { "description": "AI-generated insight body, returned verbatim from the analytics service. The shape follows `type`: `aiInsightsSummary` returns `health_score`, `health_label`, `status_summary`, `summary_text` and exactly 3 `highlights`; `aiInsightsDetailed` returns `status_headline`, `status_reason`, `status_tone`, 3 `executive_summary` bullets, 6 `metrics`, `whats_happening` (an intro plus root-cause/effect/impact steps), 3-4 `actions` and 3 `suggested_prompts`. Every field is model-generated, so treat each as optional.", "type": "object", "example": { "success": true, "health_score": 78, "health_label": "Good", "status_summary": "Shorts driving growth", "summary_text": "Shorts added subscribers **1.8x** faster than long-form uploads.", "highlights": [ "...", "...", "..." ], "confidence": "High" }, "additionalProperties": true }, "message": { "type": "string", "example": "", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUnauthorized" } } } }, "403": { "description": "Workspace permission denied. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsForbidden" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRateLimited" } } } }, "502": { "description": "Upstream analytics service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsUpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/approval-workflows/cascade-jobs/{cascade_job_id}": { "get": { "tags": [ "⏳ Approval Cascade Jobs" ], "summary": "Get cascade job status", "description": "Poll the progress of a cascade dispatched by an approval-workflow update (`confirmed=true`) or a force delete. Terminal states are `completed`, `partially_failed` (finished, with per-post problems listed in `failures`) and `failed`.", "operationId": "fetchApprovalCascadeJob", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "cascade_job_id", "in": "path", "description": "Cascade job id returned by a 202 response", "required": true, "schema": { "type": "string", "example": "66b0c1d2e3f4a5b6c7d8e9f0" } } ], "responses": { "200": { "description": "Cascade job retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CascadeJobFetched" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace, or missing the `manage_workflow` permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowForbidden" } } } }, "404": { "description": "Cascade job not found in this workspace (`CASCADE_JOB_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CascadeJobNotFound" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/approval-workflows": { "get": { "tags": [ "βœ… Approval Workflows" ], "summary": "List approval workflows", "description": "Retrieve the workspace's published (non-draft) multi-level approval workflows. Use the returned `id` as `approval_workflow.workflow_id` when creating or updating a post. Requires the `manage_workflow` permission.", "operationId": "fetchApprovalWorkflows", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Approval workflows retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowList" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace, or missing the `manage_workflow` permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowForbidden" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "βœ… Approval Workflows" ], "summary": "Create an approval workflow", "description": "Create a multi-level approval workflow with up to 5 levels. Every member referenced in `levels[].members[]` must belong to the workspace team. A workflow with any level that has no members is stored as a draft and cannot be set as default. `is_default` is not accepted β€” use the set-default endpoint. Requires the `manage_workflow` permission.", "operationId": "createApprovalWorkflow", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "levels" ], "properties": { "name": { "type": "string", "maxLength": 120, "example": "Marketing Approval" }, "is_draft": { "description": "Force draft status. A workflow with an unstaffed level is a draft regardless.", "type": "boolean", "example": false }, "levels": { "type": "array", "items": { "required": [ "level_number", "rule", "members" ], "properties": { "level_number": { "description": "Unique across the payload.", "type": "integer", "maximum": 5, "minimum": 1, "example": 1 }, "title": { "type": "string", "maxLength": 255, "example": "Editors", "nullable": true }, "rule": { "type": "string", "enum": [ "anyone", "everyone" ], "example": "anyone" }, "members": { "type": "array", "items": { "properties": { "user_id": { "type": "string", "example": "627a078300a7d866600e7d02" } }, "type": "object" } } }, "type": "object" }, "maxItems": 5, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Approval workflow created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowCreated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace, or missing the `manage_workflow` permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowForbidden" } } } }, "422": { "description": "Validation failed β€” duplicate level numbers, duplicate members in a level, a member outside the workspace, or more than 5 levels β€” or the create failed (`APPROVAL_WORKFLOW_CREATE_FAILED`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApprovalWorkflowValidationError" }, { "$ref": "#/components/schemas/ApprovalWorkflowWriteFailed" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/approval-workflows/{workflow_id}": { "get": { "tags": [ "βœ… Approval Workflows" ], "summary": "Get a single approval workflow", "description": "Retrieve one approval workflow, including drafts, plus its runtime in-flight metrics. `in_flight_posts_count` is the number of posts currently pending or partially approved against this workflow β€” check it before deleting, since a non-zero count requires `force=true`.", "operationId": "fetchApprovalWorkflow", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "workflow_id", "in": "path", "description": "Approval workflow id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890d" } } ], "responses": { "200": { "description": "Approval workflow retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowFetched" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace, or missing the `manage_workflow` permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowForbidden" } } } }, "404": { "description": "Approval workflow not found in this workspace (`APPROVAL_WORKFLOW_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowNotFound" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "βœ… Approval Workflows" ], "summary": "Update an approval workflow", "description": "Partially update an approval workflow β€” fields that are not provided keep their current values. The definition is always saved. Posts already in review keep the workflow snapshot they were submitted under unless `confirmed=true` is passed, which additionally re-applies the new levels to them via a background cascade and answers 202 with a `cascade_job_id` to poll.", "operationId": "updateApprovalWorkflow", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "workflow_id", "in": "path", "description": "Approval workflow id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890d" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 120, "example": "Marketing Approval v2" }, "is_draft": { "type": "boolean", "example": false }, "confirmed": { "description": "Re-apply the new levels to posts already in review. Without it those posts keep their existing snapshot.", "type": "boolean", "example": false }, "levels": { "type": "array", "items": { "required": [ "level_number", "rule", "members" ], "properties": { "level_number": { "description": "Unique across the payload.", "type": "integer", "maximum": 5, "minimum": 1, "example": 1 }, "title": { "type": "string", "maxLength": 255, "example": "Editors", "nullable": true }, "rule": { "type": "string", "enum": [ "anyone", "everyone" ], "example": "anyone" }, "members": { "type": "array", "items": { "properties": { "user_id": { "type": "string", "example": "627a078300a7d866600e7d02" } }, "type": "object" } } }, "type": "object" }, "maxItems": 5, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Approval workflow updated. The definition is saved; posts already in review keep their existing snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUpdated" } } } }, "202": { "description": "Updated, and a cascade over posts already in review was dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUpdateCascading" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace, or missing the `manage_workflow` permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowForbidden" } } } }, "404": { "description": "Approval workflow not found in this workspace (`APPROVAL_WORKFLOW_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowNotFound" } } } }, "422": { "description": "Validation failed (`VALIDATION_ERROR`), or the update failed (`APPROVAL_WORKFLOW_UPDATE_FAILED`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApprovalWorkflowValidationError" }, { "$ref": "#/components/schemas/ApprovalWorkflowWriteFailed" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "βœ… Approval Workflows" ], "summary": "Delete an approval workflow", "description": "Delete an approval workflow. If posts are currently in review against it the call is refused with `REQUIRES_FORCE_DELETE` and the affected count, unless `force=true` is passed β€” in which case the workflow is deleted and those posts are cleaned up by a background cascade (202 + `cascade_job_id`). Deleting the workspace's default workflow leaves the workspace with no default until another is promoted; the response reports this via `was_default`.", "operationId": "deleteApprovalWorkflow", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "workflow_id", "in": "path", "description": "Approval workflow id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890d" } }, { "name": "force", "in": "query", "description": "Delete even when posts are in review against this workflow.", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Approval workflow deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowDeleted" } } } }, "202": { "description": "Deleted, and a cascade over posts already in review was dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowDeleteCascading" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace, or missing the `manage_workflow` permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowForbidden" } } } }, "404": { "description": "Approval workflow not found in this workspace (`APPROVAL_WORKFLOW_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowNotFound" } } } }, "422": { "description": "Posts are in review and `force` was not passed (`REQUIRES_FORCE_DELETE`), or the delete failed (`APPROVAL_WORKFLOW_DELETE_FAILED`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApprovalWorkflowForceDeleteRequired" }, { "$ref": "#/components/schemas/ApprovalWorkflowWriteFailed" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/approval-workflows/{workflow_id}/duplicate": { "post": { "tags": [ "βœ… Approval Workflows" ], "summary": "Duplicate an approval workflow", "description": "Create a copy of an approval workflow, named ` (Copy)`. The clone is never the default, even when the source is. It inherits the source's draft status, so duplicating a draft yields a draft. The target workspace is resolved from the source workflow and cannot be supplied by the caller.", "operationId": "duplicateApprovalWorkflow", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "workflow_id", "in": "path", "description": "Approval workflow id to copy", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890d" } } ], "responses": { "201": { "description": "Approval workflow duplicated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowDuplicated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace, or missing the `manage_workflow` permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowForbidden" } } } }, "404": { "description": "Approval workflow not found in this workspace (`APPROVAL_WORKFLOW_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowNotFound" } } } }, "422": { "description": "Duplicate failed (`APPROVAL_WORKFLOW_DUPLICATE_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowWriteFailed" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/approval-workflows/{workflow_id}/set-default": { "put": { "tags": [ "βœ… Approval Workflows" ], "summary": "Set an approval workflow as the workspace default", "description": "Promote a workflow to the workspace default. The previous default is unset atomically as part of the same operation. Calling this on the workflow that is already the default is a successful no-op. Draft workflows cannot be made default.", "operationId": "setDefaultApprovalWorkflow", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "workflow_id", "in": "path", "description": "Approval workflow id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890d" } } ], "responses": { "200": { "description": "Approval workflow set as default. Calling this on the current default is a successful no-op", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowDefaultSet" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace, or missing the `manage_workflow` permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowForbidden" } } } }, "404": { "description": "Approval workflow not found in this workspace (`APPROVAL_WORKFLOW_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowNotFound" } } } }, "422": { "description": "The workflow is a draft (`CANNOT_SET_DRAFT_AS_DEFAULT`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowDraftDefaultRejected" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/approval-workflows/{workflow_id}/remove-default": { "put": { "tags": [ "βœ… Approval Workflows" ], "summary": "Remove an approval workflow's default status", "description": "Demote the workspace default, leaving the workspace with no default workflow until another is promoted. Calling this on a workflow that is not the default is a successful no-op. Draft workflows are rejected, mirroring set-default β€” a draft can never have been the default.", "operationId": "removeDefaultApprovalWorkflow", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "workflow_id", "in": "path", "description": "Approval workflow id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890d" } } ], "responses": { "200": { "description": "Default removed. Calling this on a workflow that is not the default is a successful no-op", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowDefaultRemoved" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace, or missing the `manage_workflow` permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowForbidden" } } } }, "404": { "description": "Approval workflow not found in this workspace (`APPROVAL_WORKFLOW_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowNotFound" } } } }, "422": { "description": "The workflow is a draft (`CANNOT_SET_DRAFT_AS_DEFAULT`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowDraftDefaultRejected" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalWorkflowRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/bulk": { "get": { "tags": [ "πŸ“₯ Bulk Automations" ], "summary": "List bulk uploads", "operationId": "listBulkAutomations", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Bulk uploads retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "automations": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“₯ Bulk Automations" ], "summary": "Submit a bulk post file", "description": "Uploads a CSV of posts and queues it for processing. Returns 202 immediately β€” the rows are built in the background, so this never blocks. Poll GET .../automations/bulk/{csv_id} every `poll_after_seconds` until `state` is `ready` (or `failed`), then review the rows and approve them. **There is no confirm-the-batch step**: parsing creates the rows, so they exist by the time you can read them. The file must be csv or txt, at most 10 MB and at most 500 data rows; a file over either limit is refused before any processing starts. Download GET .../automations/bulk/sample-file for a valid file with the exact columns.", "operationId": "submitBulkAutomation", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "inputFile", "account", "name", "dateSettingType" ], "properties": { "inputFile": { "description": "The CSV file of posts; max 10 MB, max 500 data rows", "type": "string", "format": "binary" }, "account": { "description": "JSON-encoded object of platform => account ids to post to. Ids are the `id` GET /accounts returns (the platform identifier); an unknown id is refused with 422 INVALID_ACCOUNT_ID before the file is processed.", "type": "string", "example": "{\"facebook\":[\"1329910333529595\"],\"instagram\":[\"17841453340834745\"]}" }, "name": { "type": "string", "example": "March promo batch" }, "dateSettingType": { "description": "Where each post's time comes from. `Custom` reads column 1 of the file and requires `format`. `Recurring` spaces posts out and requires `recurring`. `content_category` uses a category's slots and requires `content_category_id`. `Queue` uses each account's queue times β€” and is the only mode where the post count is multiplied by the number of selected accounts.", "type": "string", "enum": [ "Custom", "Recurring", "content_category", "Queue" ], "example": "Custom" }, "format": { "description": "Required when dateSettingType is Custom: how column 1 is written.", "type": "string", "enum": [ "d/m/Y H:i", "m/d/Y H:i" ], "example": "d/m/Y H:i" }, "recurring": { "description": "Required when dateSettingType is Recurring.", "properties": { "type": { "type": "string", "enum": [ "Hour", "Day", "Week" ] }, "value": { "type": "integer", "example": 6 } }, "type": "object" }, "content_category_id": { "description": "Required when dateSettingType is content_category.", "type": "string", "nullable": true }, "first_comment_accounts": { "description": "Account ids (as in `account`) that should post column 5 as a first comment. Each must be one of the ids in `account` and on a platform with first comments (facebook, instagram, linkedin, youtube, telegram); anything else is refused with 422 β€” INVALID_ACCOUNT_ID for an unknown id, VALIDATION_ERROR otherwise.", "type": "array", "items": { "type": "string", "example": "1329910333529595" } } }, "type": "object" } } } }, "responses": { "202": { "description": "File accepted and queued. Not yet processed β€” poll the status endpoint.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "csv_id": { "description": "Use this to poll status and list rows", "type": "string", "example": "csv_8f2a1c" }, "total": { "description": "Posts the file will produce β€” rows Γ— selected accounts when dateSettingType is Queue, otherwise rows", "type": "integer", "example": 120 }, "poll_after_seconds": { "type": "integer", "example": 5 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "Unknown account id (INVALID_ACCOUNT_ID, names the id and platform; the file is not processed), too many rows (ROW_LIMIT_EXCEEDED), unreadable file (BULK_FILE_INVALID), empty file (NO_DATA_IN_FILE), upload failed (BULK_UPLOAD_FAILED) or validation error (VALIDATION_ERROR). BULK_UPLOAD_FAILED and BULK_FILE_INVALID carry a `detail` field with what specifically was wrong.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "One or more account IDs are not valid for this workspace." }, "error_code": { "type": "string", "example": "INVALID_ACCOUNT_ID" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/bulk/sample-file": { "get": { "tags": [ "πŸ“₯ Bulk Automations" ], "summary": "Download a sample bulk file", "description": "A valid CSV with the exact columns a bulk submission expects, in order. The parser reads columns by **position**, not by header text, so the header row can say anything β€” but the order cannot change. Column 1 is only read when `dateSettingType` is `Custom`. Multiple image URLs go in column 3 separated by newlines. Column 6 accepts `no` to stop the column 4 link being appended to the message.", "operationId": "downloadBulkAutomationSampleFile", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "A ready-to-edit sample file", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/bulk/{csv_id}": { "get": { "tags": [ "πŸ“₯ Bulk Automations" ], "summary": "Get bulk upload status", "description": "Progress of a queued bulk file. `queued` and `parsing` are not finished β€” call this endpoint again after `poll_after_seconds`. `ready` and `failed` are terminal: on `ready` the rows are built and can be listed and approved, on `failed` the batch produced nothing approvable and `failure_reason` says why. `errored_rows` counts rows that cannot be approved as they stand; those rows carry their own error in the rows listing. A batch whose background job dies mid-run keeps reporting `parsing`, because nothing records job death.", "operationId": "getBulkAutomationStatus", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "csv_id", "in": "path", "required": true, "schema": { "type": "string", "example": "csv_8f2a1c" } } ], "responses": { "200": { "description": "Status retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "state": { "description": "`queued`/`parsing`: poll again after poll_after_seconds. `ready`/`failed`: terminal.", "type": "string", "enum": [ "queued", "parsing", "ready", "failed" ], "example": "parsing" }, "total": { "type": "integer", "example": 120 }, "processed": { "type": "integer", "example": 48 }, "errored_rows": { "description": "Rows that cannot be approved as they stand", "type": "integer", "example": 2 }, "poll_after_seconds": { "type": "integer", "example": 5 }, "failure_reason": { "description": "Present only when state is `failed`", "type": "string", "example": "error_date,error_image", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "No such bulk upload in this workspace (BATCH_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Bulk upload not found." }, "error_code": { "type": "string", "example": "BATCH_NOT_FOUND" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“₯ Bulk Automations" ], "summary": "Abandon a bulk upload", "description": "Throws away everything in the batch that is still pending, so nothing further from this file is ever scheduled. Rows already approved are **not** touched: approving created a scheduled post through the normal planner path, and the response reports those separately as `already_approved` so the distinction is explicit. To withdraw an approved post, delete the post itself. Irreversible.", "operationId": "abandonBulkAutomation", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "csv_id", "in": "path", "required": true, "schema": { "type": "string", "example": "csv_8f2a1c" } } ], "responses": { "200": { "description": "Batch abandoned", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "deleted": { "description": "Pending rows deleted; none of them was scheduled", "type": "integer", "example": 98 }, "already_approved": { "description": "Rows approved before this call; their scheduled posts are untouched", "type": "integer", "example": 22 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "No such bulk upload in this workspace (BATCH_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Bulk upload not found." }, "error_code": { "type": "string", "example": "BATCH_NOT_FOUND" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/bulk/{csv_id}/rows": { "get": { "tags": [ "πŸ“₯ Bulk Automations" ], "summary": "List the rows a bulk upload produced", "description": "The posts built from the uploaded file, awaiting review. A row that could not be built carries its own `error` β€” problems are attached to the row they affect, never aggregated onto the batch. Aggregate counts are returned on every page.", "operationId": "listBulkAutomationRows", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "csv_id", "in": "path", "required": true, "schema": { "type": "string", "example": "csv_8f2a1c" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Rows retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/bulk/{csv_id}/rows/actions": { "post": { "tags": [ "πŸ“₯ Bulk Automations" ], "summary": "Approve or delete bulk upload rows", "description": "Approves the named rows β€” which is what schedules them β€” or deletes them. Approving respects your own permission: without `schedule_plan` a row goes into the approval flow for review instead of straight to scheduled, exactly as in the web app. Rows carrying an error are skipped rather than approved. Only rows created by the API key's own user can be acted on, matching how the web app scopes these actions per user. Deletion is permanent.", "operationId": "actOnBulkAutomationRows", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "csv_id", "in": "path", "required": true, "schema": { "type": "string", "example": "csv_8f2a1c" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids", "type" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "example": [ "625d06734ceb636c2f5e7743" ] }, "type": { "type": "string", "enum": [ "approve", "delete" ], "example": "approve" } }, "type": "object" } } } }, "responses": { "200": { "description": "Rows updated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "No row in this batch matched the given ids (BATCH_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Bulk upload not found." }, "error_code": { "type": "string", "example": "BATCH_NOT_FOUND" } }, "type": "object" } } } }, "422": { "description": "Row action failed (ROW_ACTION_FAILED) or validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid plan. Please try again." }, "error_code": { "type": "string", "example": "ROW_ACTION_FAILED" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/bulk/{csv_id}/rows/labels": { "post": { "tags": [ "πŸ“₯ Bulk Automations" ], "summary": "Attach labels to bulk upload rows", "description": "Sets the labels on pending rows, before they are approved. This **replaces** each row's label list rather than adding to it β€” send the full set you want. Label ids come from GET /workspaces/{workspace_id}/labels.", "operationId": "attachBulkAutomationRowLabels", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "csv_id", "in": "path", "required": true, "schema": { "type": "string", "example": "csv_8f2a1c" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids", "label_ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "example": [ "625d06734ceb636c2f5e7743" ] }, "label_ids": { "description": "The complete label set for these rows; an empty array clears them", "type": "array", "items": { "type": "string" }, "example": [ "64a1f0c2b4e2a10012ab34cd" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Labels attached", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "No row in this batch matched the given ids (BATCH_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Bulk upload not found." }, "error_code": { "type": "string", "example": "BATCH_NOT_FOUND" } }, "type": "object" } } } }, "422": { "description": "No valid rows (NO_VALID_ROWS) or validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No valid entries found with the provided IDs." }, "error_code": { "type": "string", "example": "NO_VALID_ROWS" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/bulk/{csv_id}/rows/campaign": { "post": { "tags": [ "πŸ“₯ Bulk Automations" ], "summary": "Attach a campaign to bulk upload rows", "description": "Puts pending rows in a campaign (folder), before they are approved. Campaign ids come from GET /workspaces/{workspace_id}/campaigns.", "operationId": "attachBulkAutomationRowCampaign", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "csv_id", "in": "path", "required": true, "schema": { "type": "string", "example": "csv_8f2a1c" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids", "campaign_id" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "example": [ "625d06734ceb636c2f5e7743" ] }, "campaign_id": { "type": "string", "example": "64a1f0c2b4e2a10012ab34cd" } }, "type": "object" } } } }, "responses": { "200": { "description": "Campaign attached", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "No row in this batch matched the given ids (BATCH_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Bulk upload not found." }, "error_code": { "type": "string", "example": "BATCH_NOT_FOUND" } }, "type": "object" } } } }, "422": { "description": "No valid rows (NO_VALID_ROWS) or validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No valid entries found with the provided IDs." }, "error_code": { "type": "string", "example": "NO_VALID_ROWS" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/evergreen": { "get": { "tags": [ "♻️ Evergreen Automations" ], "summary": "List evergreen automations", "operationId": "listEvergreenAutomations", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Filter by automation name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Automations retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "automations": { "description": "Paginator with the evergreen automations under `data`", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "♻️ Evergreen Automations" ], "summary": "Create an evergreen automation", "description": "Creates an evergreen automation that recycles a pool of posts on a repeating schedule. Counts against the workspace's automation plan limit β€” a workspace at its limit gets 422 AUTOMATION_LIMIT_REACHED with a limit_details breakdown.", "operationId": "createEvergreenAutomation", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "account_selection", "schedule_options", "posts", "cycleGapStatus" ], "properties": { "name": { "type": "string", "example": "Blog evergreen" }, "account_selection": { "description": "Platform => account ids the automation posts to. Ids are the `id` GET /accounts returns (the platform identifier); any other value is refused with 422 INVALID_ACCOUNT_ID.", "type": "object", "example": { "facebook": [ "1329910333529595" ], "instagram": [ "17841453340834745" ] } }, "schedule_options": { "description": "Posting schedule for the recycling cycle. `time_type` is `Recurring` (every `recurring.value` `recurring.type`, Hour|Day|Week), `Custom` (weekly slots: `custom.days` lists all seven days in order Sun..Sat, each with `status` and `times` as HH:MM) or `content_category` (posts land in `content_category_id`'s slots; the id is then required). `schedule_type` is `continuously` or `fix` with `start_time`/`end_time` (Y-m-d H:i:s). Anything outside these values is refused with 422 VALIDATION_ERROR.", "type": "object", "example": { "time_type": "Recurring", "recurring": { "type": "Hour", "value": 1 }, "custom": { "days": [ { "name": "Sun", "status": true, "times": [ "10:00" ] }, { "name": "Mon", "status": true, "times": [ "10:00" ] }, { "name": "Tue", "status": true, "times": [ "10:00" ] }, { "name": "Wed", "status": true, "times": [ "10:00" ] }, { "name": "Thu", "status": true, "times": [ "10:00" ] }, { "name": "Fri", "status": true, "times": [ "10:00" ] }, { "name": "Sat", "status": true, "times": [ "10:00" ] } ] }, "schedule_type": "continuously", "start_time": "", "end_time": "", "posting_status": "scheduled" } }, "posts": { "description": "The pool of posts to recycle. Each item becomes one pool entry, stored as a single variation in the product's own shape (see the `posts` example on the response). Same item shape as POST .../posts.", "type": "array", "items": { "required": [ "title", "url" ], "properties": { "title": { "type": "string", "maxLength": 500, "example": "How we cut build times in half" }, "url": { "description": "The link the post carries", "type": "string", "format": "uri", "example": "https://example.com/blog/build-times" }, "message": { "description": "The text that publishes. Defaults to `title`.", "type": "string", "maxLength": 5000, "example": "We cut CI from 40 to 19 minutes. Here is what moved the needle.", "nullable": true }, "description": { "type": "string", "maxLength": 5000, "example": "A short teaser shown on link previews", "nullable": true }, "image": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 10, "example": [ "https://example.com/build-times.png" ] } }, "type": "object" } }, "cycleGapStatus": { "description": "Whether a gap is enforced between cycles", "type": "boolean", "example": true }, "cycleGap": { "description": "Days between cycles. Required when `cycleGapStatus` is true.", "type": "integer", "minimum": 1, "example": 1, "nullable": true }, "replanType": { "description": "Whether changes restart the cycle now or apply from the next one.", "type": "string", "enum": [ "Now", "Later" ], "example": "Later", "nullable": true }, "content_category_id": { "description": "Required when `schedule_options.time_type` is `content_category`; must belong to the workspace.", "type": "string", "example": "669f8b8d0dfd96946502faf2", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Automation created", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "description": "The created evergreen automation", "type": "object", "example": { "_id": "6ab10c5b441ac0ca4e0b5222", "name": "Blog evergreen", "workspace_id": "610a1e660cb41530ca40d372", "status": 1, "lock": 0, "posted_count": 0, "cycleGapStatus": false, "cycleGap": 1, "replanType": "Later", "account_selection": { "facebook": [ { "_id": "6a742f84f67707aac00bc6e3", "type": "Page", "facebook_id": "1329910333529595", "name": "Company page" } ] }, "schedule_options": { "time_type": "Recurring", "recurring": { "type": "Hour", "value": 1 }, "schedule_type": "continuously", "posting_status": "scheduled" }, "posts": [ [ { "id": "6ab10c5b441ac0ca4e0b5223", "message": "We cut CI from 40 to 19 minutes. Here is what moved the needle.", "title": "How we cut build times in half", "description": "A short teaser shown on link previews", "url": "https://example.com/blog/build-times", "image": [ "https://example.com/build-times.png" ], "has_first_comment": false, "first_comment_message": "", "first_comment_accounts": [], "gmb_options": [] } ] ], "created_at": "2026-09-21T10:15:33.000000Z" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR), unknown account id (INVALID_ACCOUNT_ID, names the id and platform; nothing is written), or plan limit reached (AUTOMATION_LIMIT_REACHED, with limit_details)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/evergreen/{automation_id}": { "get": { "tags": [ "♻️ Evergreen Automations" ], "summary": "Get an evergreen automation", "operationId": "getEvergreenAutomation", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "responses": { "200": { "description": "Automation retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "description": "The evergreen automation", "type": "object", "example": { "_id": "6ab10c5b441ac0ca4e0b5222", "name": "Blog evergreen", "workspace_id": "610a1e660cb41530ca40d372", "status": 1, "lock": 0, "posted_count": 0, "cycleGapStatus": false, "cycleGap": 1, "replanType": "Later", "account_selection": { "facebook": [ { "_id": "6a742f84f67707aac00bc6e3", "type": "Page", "facebook_id": "1329910333529595", "name": "Company page" } ] }, "schedule_options": { "time_type": "Recurring", "recurring": { "type": "Hour", "value": 1 }, "schedule_type": "continuously", "posting_status": "scheduled" }, "posts": [ [ { "id": "6ab10c5b441ac0ca4e0b5223", "message": "We cut CI from 40 to 19 minutes. Here is what moved the needle.", "title": "How we cut build times in half", "description": "A short teaser shown on link previews", "url": "https://example.com/blog/build-times", "image": [ "https://example.com/build-times.png" ], "has_first_comment": false, "first_comment_message": "", "first_comment_accounts": [], "gmb_options": [] } ] ], "created_at": "2026-09-21T10:15:33.000000Z" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Automation not found in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "♻️ Evergreen Automations" ], "summary": "Delete an evergreen automation", "description": "Permanently deletes the automation AND the posts it has scheduled. Irreversible β€” automations have no archive or restore. Pause it instead (PATCH .../status with status=false) to stop publishing while keeping the post pool.", "operationId": "deleteEvergreenAutomation", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "responses": { "200": { "description": "Automation and its scheduled posts deleted", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Automation not found in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/evergreen/{automation_id}/status": { "patch": { "tags": [ "♻️ Evergreen Automations" ], "summary": "Pause or resume an evergreen automation", "description": "Sets whether the automation is active. Reversible and safe to repeat. An automation mid-run is locked and returns 409 AUTOMATION_LOCKED rather than silently doing nothing.", "operationId": "setEvergreenAutomationStatus", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "description": "true resumes the automation, false pauses it", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Status updated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Automation not found in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "409": { "description": "Automation is locked while a job runs (AUTOMATION_LOCKED)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Automation is in lock state.Cannot process multiple jobs." }, "error_code": { "type": "string", "example": "AUTOMATION_LOCKED" } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/evergreen/{automation_id}/posts": { "post": { "tags": [ "♻️ Evergreen Automations" ], "summary": "Add posts to an evergreen automation", "description": "Appends one or more posts to the automation's recycling pool in a single atomic write, so concurrent callers cannot overwrite each other β€” safe to drive from a webhook or a no-code step. Each item becomes one pool entry with a single variation, the same shape create's `posts[]` produces.", "operationId": "addEvergreenPosts", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "posts" ], "properties": { "posts": { "description": "1 to 50 posts to append.", "type": "array", "items": { "required": [ "title", "url" ], "properties": { "title": { "type": "string", "maxLength": 500, "example": "How we cut build times in half" }, "url": { "description": "The link the post carries", "type": "string", "format": "uri", "example": "https://example.com/blog/build-times" }, "message": { "description": "The text that publishes. Defaults to `title`.", "type": "string", "maxLength": 5000, "example": "We cut CI from 40 to 19 minutes. Here is what moved the needle.", "nullable": true }, "description": { "type": "string", "maxLength": 5000, "example": "A short teaser shown on link previews", "nullable": true }, "image": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 10, "example": [ "https://example.com/build-times.png" ] } }, "type": "object" }, "maxItems": 50, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Posts appended to the automation", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Posts added to the evergreen automation successfully." }, "data": { "properties": { "added": { "description": "How many posts this call appended", "type": "integer", "example": 2 }, "posts_count": { "description": "Size of the pool after the append", "type": "integer", "example": 7 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Automation not found in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR); `errors` names the offending item, e.g. `posts.1.url`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The posts.1.url field must be a valid URL." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "posts.1.url": [ "The posts.1.url field must be a valid URL." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/rss": { "get": { "tags": [ "πŸ” RSS Automations" ], "summary": "List RSS automations", "description": "Paginated list of the workspace's RSS automations.", "operationId": "listRssAutomations", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Filter by automation name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Automations retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "automations": { "description": "Paginator with the RSS automations under `data`", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ” RSS Automations" ], "summary": "Create an RSS automation", "description": "Creates an RSS feed automation that posts new feed items to the selected accounts. The feed URL is fetched and validated before the automation is saved, so an unreachable feed fails the request. Counts against the workspace's automation plan limit.", "operationId": "createRssAutomation", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "account_selection", "feed_url", "posting_type", "max_post", "review_content" ], "properties": { "name": { "type": "string", "example": "Company blog" }, "account_selection": { "description": "Platform => account ids the automation posts to. Ids are the `id` GET /accounts returns (the platform identifier); any other value is refused with 422 INVALID_ACCOUNT_ID.", "type": "object", "example": { "facebook": [ "1329910333529595" ], "instagram": [ "17841453340834745" ] } }, "feed_url": { "type": "string", "format": "uri", "example": "https://example.com/feed.xml" }, "posting_type": { "description": "What happens to each new feed item: `Immediately` publishes it, `Queue` adds it to each account's queue (see `queue_slot_option`), `content_category` files it under `content_category_id` (required then). Case-sensitive.", "type": "string", "enum": [ "Immediately", "Queue", "content_category" ], "example": "Queue" }, "max_post": { "description": "Maximum items published per pull", "type": "integer", "maximum": 50, "minimum": 1, "example": 5 }, "review_content": { "description": "Queue items for review instead of publishing straight away", "type": "boolean", "example": true }, "content_category_id": { "type": "string", "nullable": true }, "add_link_first_comment": { "type": "boolean", "nullable": true }, "add_source_in_description": { "description": "Append the feed item's source to the post", "type": "boolean", "nullable": true }, "post_variations": { "description": "Which part of the feed item becomes the post body: `body_content` (AI-generated caption when credits allow), `post_title` (title + URL) or `meta_description`", "type": "string", "enum": [ "body_content", "post_title", "meta_description" ], "example": "body_content", "nullable": true }, "queue_slot_option": { "description": "Where in the account queue new items land", "type": "string", "enum": [ "top", "bottom" ], "nullable": true }, "pull_frequency": { "description": "How often the feed is checked. Defaults to 30m.", "type": "string", "enum": [ "5m", "15m", "30m", "1h", "3h", "6h", "12h", "24h" ], "example": "30m" }, "replug": { "description": "Replug link shortening. `brand` and `campaign` are required when `status` is true.", "properties": { "status": { "type": "boolean" }, "brand": { "type": "string" }, "campaign": { "type": "string" } }, "type": "object", "nullable": true }, "hashtag": { "description": "Hashtag set to append. `id` is required when `status` is true.", "properties": { "status": { "type": "boolean" }, "id": { "type": "string" } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Automation created", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "description": "The created RSS automation. `lock` is 1 while the first feed pull runs (a few seconds); status changes and updates answer 409 AUTOMATION_LOCKED until it clears.", "type": "object", "example": { "_id": "6ab10a1159c890e5c8014593", "name": "Company blog", "feed_url": "https://example.com/feed.xml", "workspace_id": "610a1e660cb41530ca40d372", "status": 1, "lock": 1, "posted_count": 0, "posting_type": "queue", "pull_frequency": "1h", "max_post": 5, "review_content": true, "post_variations": "body_content", "account_selection": { "facebook": [ { "_id": "6a742f84f67707aac00bc6e3", "type": "Page", "facebook_id": "1329910333529595", "name": "Company page" } ] }, "created_at": "2026-09-21T10:15:33.000000Z" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR), unknown account id (INVALID_ACCOUNT_ID, names the id and platform; nothing is written), unreachable feed (INVALID_FEED_URL), or plan limit reached (AUTOMATION_LIMIT_REACHED, with limit_details)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/rss/{automation_id}": { "get": { "tags": [ "πŸ” RSS Automations" ], "summary": "Get an RSS automation", "operationId": "getRssAutomation", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "responses": { "200": { "description": "Automation retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "description": "The RSS automation", "type": "object", "example": { "_id": "6ab10a1159c890e5c8014593", "name": "Company blog", "feed_url": "https://example.com/feed.xml", "workspace_id": "610a1e660cb41530ca40d372", "status": 1, "lock": 1, "posted_count": 0, "posting_type": "queue", "pull_frequency": "1h", "max_post": 5, "review_content": true, "post_variations": "body_content", "account_selection": { "facebook": [ { "_id": "6a742f84f67707aac00bc6e3", "type": "Page", "facebook_id": "1329910333529595", "name": "Company page" } ] }, "created_at": "2026-09-21T10:15:33.000000Z" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Automation not found in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "πŸ” RSS Automations" ], "summary": "Update an RSS automation", "description": "Changes an existing automation's feed or settings. Fields you omit keep their current values, with one exception: **`account_selection` is always required**. The stored selection is persisted expanded and has to be re-resolved against the workspace's live accounts to be saved again, so anything since disconnected, revoked or moved would be silently dropped β€” a PUT therefore states the accounts it wants rather than inheriting a list that may no longer be valid. The feed URL is re-validated, so pointing an automation at an unreachable feed fails the request rather than quietly breaking it. Updating does **not** consume automation allowance β€” only creating does. An automation mid-pull is locked and returns 409 rather than being edited underneath its running job.", "operationId": "updateRssAutomation", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "requestBody": { "description": "Any subset of the create payload, plus account_selection, which is always required.", "required": true, "content": { "application/json": { "schema": { "required": [ "account_selection" ], "properties": { "name": { "type": "string", "example": "Company blog" }, "account_selection": { "description": "Required. The complete account set the automation should post to after this update, as the `id` values GET /accounts returns. An unknown id is refused with 422 INVALID_ACCOUNT_ID and nothing is written.", "type": "object", "example": { "facebook": [ "1329910333529595" ], "instagram": [ "17841453340834745" ] } }, "feed_url": { "type": "string", "format": "uri", "example": "https://example.com/feed.xml" }, "posting_type": { "type": "string" }, "max_post": { "type": "integer", "example": 5 }, "review_content": { "type": "boolean" }, "pull_frequency": { "type": "string", "example": "1h" }, "content_category_id": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Automation updated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "description": "The updated RSS automation", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "No such automation in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "409": { "description": "Automation is mid-pull (AUTOMATION_LOCKED)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Automation is in lock state.Cannot process multiple jobs." }, "error_code": { "type": "string", "example": "AUTOMATION_LOCKED" } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR), unknown account id (INVALID_ACCOUNT_ID, names the id and platform; nothing is written) or unreachable feed (INVALID_FEED_URL)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ” RSS Automations" ], "summary": "Delete an RSS automation", "description": "Permanently deletes the automation AND the posts it has scheduled. Irreversible β€” there is no archive or restore for automations. Pause the automation instead (PATCH .../status with status=false) if you only want it to stop publishing.", "operationId": "deleteRssAutomation", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "responses": { "200": { "description": "Automation and its scheduled posts deleted", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "queued_posts_removed": { "description": "Posts this automation had queued that were deleted with it. Posts it already published are not touched.", "type": "integer", "example": 14 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Automation not found in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/rss/{automation_id}/status": { "patch": { "tags": [ "πŸ” RSS Automations" ], "summary": "Pause or resume an RSS automation", "description": "Sets whether the automation is active. Reversible and safe to repeat. An automation that is mid-run is locked and cannot change status until its job finishes β€” that returns 409 AUTOMATION_LOCKED rather than silently doing nothing.", "operationId": "setRssAutomationStatus", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "description": "true resumes the automation, false pauses it", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Status updated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "queued_posts_retained": { "description": "Posts already queued by this automation. Pausing does NOT withdraw them β€” unlike deleting, they still go out. Delete the posts themselves to stop them.", "type": "integer", "example": 14 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Automation not found in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "409": { "description": "Automation is locked while a job runs (AUTOMATION_LOCKED)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Automation is in lock state.Cannot process multiple jobs." }, "error_code": { "type": "string", "example": "AUTOMATION_LOCKED" } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/rss/validate-feed": { "post": { "tags": [ "πŸ” RSS Automations" ], "summary": "Check an RSS feed URL", "description": "Fetches the feed and reports whether it is readable, without creating anything. Use this before createRssAutomation when the URL came from an end user, so a bad feed is reported as its own failure rather than as a failed create.", "operationId": "validateRssFeedUrl", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "feed_url" ], "properties": { "feed_url": { "type": "string", "format": "uri", "example": "https://example.com/feed.xml" } }, "type": "object" } } } }, "responses": { "200": { "description": "Feed URL is valid and reachable", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "422": { "description": "Feed unreachable or not a feed (INVALID_FEED_URL), or validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Feed unreachable or not a feed" }, "error_code": { "type": "string", "example": "INVALID_FEED_URL" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/rss/{automation_id}/history-pull": { "post": { "tags": [ "πŸ” RSS Automations" ], "summary": "Pull the feed's history now", "description": "Runs the automation's feed pull immediately instead of waiting for its `pull_frequency`, which is how a feed is backfilled. The pull happens in the background: this returns 202 and the posts appear on the automation as it works. Items already published by this automation are skipped, so a repeat pull does not duplicate them. **Rate limited to 5 requests per hour per workspace** β€” a pull is a feed fetch plus a queue write, and the scheduler already pulls on its own, so this is a backfill tool rather than a polling mechanism. A pull already in flight returns 409 rather than stacking a second one.", "operationId": "pullRssAutomationHistory", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "responses": { "202": { "description": "Pull started in the background", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "No such automation in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "409": { "description": "A pull is already running (HISTORY_PULL_IN_PROGRESS) or the automation is locked (AUTOMATION_LOCKED)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A feed history pull is already running for this automation. Wait for it to finish before starting another." }, "error_code": { "type": "string", "example": "HISTORY_PULL_IN_PROGRESS" } }, "type": "object" } } } }, "429": { "description": "Rate limit exceeded (RATE_LIMIT_EXCEEDED)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/rss/{automation_id}/history": { "get": { "tags": [ "πŸ” RSS Automations" ], "summary": "Read an RSS automation's pull history", "description": "What each feed pull did β€” how many new items it found and how many posts it created, or that it found nothing. This is the automation's own log; for the posts themselves use the `/posts` endpoint.", "operationId": "getRssAutomationHistory", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Pull history retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "description": "Pull records, most recent first", "type": "array", "items": { "type": "object" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 142 }, "last_page": { "type": "integer", "example": 8 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "No such automation in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/automations/rss/{automation_id}/posts": { "get": { "tags": [ "πŸ” RSS Automations" ], "summary": "Read an RSS automation's posts", "description": "The posts this automation produced. `status=published` is what it has already published; `status=queued` is what it will publish next, in execution order. Posts come back in exactly the shape GET /workspaces/{workspace_id}/posts returns, because they are the same posts read through the same repository β€” an automation's output is not a separate kind of post.", "operationId": "listRssAutomationPosts", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } }, { "name": "status", "in": "query", "description": "Which side of the automation's timeline to read", "schema": { "type": "string", "default": "queued", "enum": [ "published", "queued" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Posts retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "description": "Posts, in the same shape as the posts endpoint", "type": "array", "items": { "type": "object" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 57 }, "last_page": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "No such automation in this workspace (AUTOMATION_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find automation." }, "error_code": { "type": "string", "example": "AUTOMATION_NOT_FOUND" } }, "type": "object" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/brand": { "get": { "tags": [ "🧠 Brand Knowledge" ], "summary": "Get the workspace brand", "description": "Returns the whole brand: style, profile, voice, a summary of source materials and the brand assets. A workspace without a brand returns `is_set_up: false` with empty sections β€” not an error.", "operationId": "getBrand", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Brand retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandForbidden" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "🧠 Brand Knowledge" ], "summary": "Create the workspace brand from your sources", "description": "Builds the brand the same way as **Build My Brand Knowledge** in the app: AI analyses the sources you give β€” website, brand text, documents and the recent posts of social accounts β€” and fills in the brand style, profile and voice. At least one source is required. The call is synchronous and can take up to two minutes. Images the analysis discovers are added to `brand_assets` in the background shortly after. A workspace has one brand: if it already has one (anything the Brand Knowledge editor would show) the call returns 409 β€” edit it with PATCH. An empty brand record is filled in, as in the app.", "operationId": "createBrand", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandCreate" } } } }, "responses": { "201": { "description": "Brand created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandCreatedResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandForbidden" } } } }, "409": { "description": "The workspace already has a brand (`BRAND_ALREADY_EXISTS`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandError" } } } }, "422": { "description": "Validation failed (including a `social_accounts` id that is not a connected account of a supported platform), or the sources held too little to build a brand (`BRAND_INSUFFICIENT_CONTENT`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BrandValidationError" }, { "$ref": "#/components/schemas/BrandError" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRateLimited" } } } }, "502": { "description": "The analysis did not complete (`BRAND_ANALYSIS_FAILED`); nothing was saved β€” retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "🧠 Brand Knowledge" ], "summary": "Delete the workspace brand", "description": "Permanently deletes the brand with its brand assets, logo and source-material files β€” the app's own delete. Posts already generated are kept. The response reports what was removed.", "operationId": "deleteBrand", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Brand deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandDeleted" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandForbidden" } } } }, "404": { "description": "The workspace has no brand (`BRAND_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "patch": { "tags": [ "🧠 Brand Knowledge" ], "summary": "Update the workspace brand", "description": "Partial update. Only the fields sent change: writing `brand_voice.tone` leaves the rest of the voice, the style and the profile untouched. A list field sent replaces that list. Creates the brand if the workspace has none.", "operationId": "updateBrand", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandWrite" } } } }, "responses": { "200": { "description": "Brand updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUpdatedResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandForbidden" } } } }, "422": { "description": "Validation failed β€” including a limit (6 colors, one each of brand/background/text, 200 characters per list entry, 10 000 per text field) or a logo in ContentStudio storage that is not the current one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandValidationError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/brand/sources": { "post": { "tags": [ "🧠 Brand Knowledge" ], "summary": "Add source materials to the brand", "description": "The app's **Add Source Material**: each source β€” the website, the text, each document, and the social accounts together β€” is saved as a source material and then analysed into the existing brand, in that order. A source the analysis cannot use is kept with `status: unreachable`; the others are not affected. Synchronous; allow up to two minutes per source. The brand must already exist.", "operationId": "addBrandSources", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandCreate" } } } }, "responses": { "201": { "description": "Sources added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandSourcesAdded" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandForbidden" } } } }, "404": { "description": "The workspace has no brand (`BRAND_NOT_FOUND`) β€” create it first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandError" } } } }, "422": { "description": "Validation failed (including an unconnected `social_accounts` id or more than 50 sources on the brand), or `BRAND_SOURCE_ADD_FAILED`", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BrandValidationError" }, { "$ref": "#/components/schemas/BrandError" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/brand/sources/{source_id}": { "delete": { "tags": [ "🧠 Brand Knowledge" ], "summary": "Delete a source material", "description": "Removes the source and the brand assets it produced. A document used as guidance by inbox auto-reply rules is detached from them; the response names those rules. The rest of the brand is unchanged.", "operationId": "deleteBrandSource", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "source_id", "in": "path", "description": "The source's `id` from `source_materials`", "required": true, "schema": { "type": "string", "example": "0b6c1f0e-8c1e-4d4c-9c43-6f1f3b0f9a11" } } ], "responses": { "200": { "description": "Source deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandSourceDeleted" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandForbidden" } } } }, "404": { "description": "No brand (`BRAND_NOT_FOUND`) or no such source (`BRAND_SOURCE_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/brand/{section}": { "get": { "tags": [ "🧠 Brand Knowledge" ], "summary": "Get one part of the brand", "description": "Returns only the brand style, the brand profile or the brand voice, with `updated_at`. A workspace without a brand returns that part empty.", "operationId": "getBrandSection", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "section", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "style", "profile", "voice" ] } } ], "responses": { "200": { "description": "Section retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandSectionResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandForbidden" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/brand/sync": { "post": { "tags": [ "🧠 Brand Knowledge" ], "summary": "Re-sync the brand from its sources", "description": "The app's source **Sync** β€” an action, not a read. Re-runs the AI analysis on every source material and **overwrites** the brand style, profile and voice with the result, updates each source's `status` and `last_synced_at`, and re-harvests brand assets in the background. Each call runs the analysis again. The response is the brand after the sync. Synchronous; allow up to two minutes. To only read the brand, use `GET /brand`.", "operationId": "syncBrand", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Brand re-synced; the response is the brand after the analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandSyncedResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandForbidden" } } } }, "404": { "description": "The workspace has no brand (`BRAND_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandError" } } } }, "422": { "description": "The sources hold too little to build a brand (`BRAND_INSUFFICIENT_CONTENT`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRateLimited" } } } }, "502": { "description": "The analysis did not complete (`BRAND_ANALYSIS_FAILED`); the brand is unchanged and the sources are marked `unreachable`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/brand/post-generation-settings": { "get": { "tags": [ "🧠 Brand Knowledge" ], "summary": "Get the post generation defaults", "description": "The defaults the AI Content Library uses to generate posts for this brand. Unset values come back as the app's defaults.", "operationId": "getBrandPostSettings", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Settings retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandPostSettingsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandForbidden" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "patch": { "tags": [ "🧠 Brand Knowledge" ], "summary": "Update the post generation defaults", "description": "Changes only the fields sent. A `social_platform` must be set before anything can be saved, as in the app. Creates the brand if the workspace has none.", "operationId": "updateBrandPostSettings", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandPostSettings" } } } }, "responses": { "200": { "description": "Settings updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandPostSettingsUpdatedResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandForbidden" } } } }, "422": { "description": "Validation failed β€” including no `social_platform` stored or sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandValidationError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/campaigns": { "get": { "tags": [ "πŸ“‚ Campaigns" ], "summary": "Get campaigns for a workspace", "description": "Retrieve paginated list of campaigns (folders) for a specific workspace, sorted alphabetically by name.", "operationId": "fetchCampaigns", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (max: 100)", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "example": 10 } }, { "name": "search", "in": "query", "description": "Search term to filter campaigns by name (case-insensitive partial match)", "required": false, "schema": { "type": "string", "example": "marketing" } } ], "responses": { "200": { "description": "Campaigns retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Campaigns retrieved successfully" }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 25 }, "last_page": { "type": "integer", "example": 3 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 10 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "625d06734ceb636c2f5e7743", "deprecated": true }, "name": { "type": "string", "example": "Q1 Marketing" }, "color": { "type": "string", "example": "color_9" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“‚ Campaigns" ], "summary": "Create a campaign", "description": "Create a new campaign (folder) in the specified workspace. Color must be one of color_1..color_20.", "operationId": "createCampaign", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "color" ], "properties": { "name": { "type": "string", "maxLength": 100, "example": "Q1 Marketing" }, "color": { "type": "string", "enum": [ "color_1", "color_2", "color_3", "color_4", "color_5", "color_6", "color_7", "color_8", "color_9", "color_10", "color_11", "color_12", "color_13", "color_14", "color_15", "color_16", "color_17", "color_18", "color_19", "color_20" ], "example": "color_2" } }, "type": "object" } } } }, "responses": { "201": { "description": "Campaign created", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Campaign created successfully. Use the returned `id` as `campaign_id` when creating a post, or to update or delete this campaign." }, "data": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "625d06734ceb636c2f5e7743", "deprecated": true }, "name": { "type": "string", "example": "Q1 Marketing" }, "color": { "type": "string", "example": "color_2" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`." }, "422": { "description": "Validation failed" }, "429": { "description": "Too Many Requests - Rate limit exceeded" } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/campaigns/{campaign_id}": { "put": { "tags": [ "πŸ“‚ Campaigns" ], "summary": "Update a campaign", "description": "Update a campaign's name and/or color. Partial updates allowed β€” only the fields provided are changed.", "operationId": "updateCampaign", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "campaign_id", "in": "path", "description": "Campaign id", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 100, "example": "Q2 Marketing" }, "color": { "type": "string", "enum": [ "color_1", "color_2", "color_3", "color_4", "color_5", "color_6", "color_7", "color_8", "color_9", "color_10", "color_11", "color_12", "color_13", "color_14", "color_15", "color_16", "color_17", "color_18", "color_19", "color_20" ], "example": "color_4" } }, "type": "object" } } } }, "responses": { "200": { "description": "Campaign updated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Campaign updated successfully" }, "data": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "625d06734ceb636c2f5e7743", "deprecated": true }, "name": { "type": "string", "example": "Q2 Marketing" }, "color": { "type": "string", "example": "color_4" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to this workspace" } }, "type": "object" } } } }, "404": { "description": "Campaign not found in this workspace", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Campaign not found in this workspace" } }, "type": "object" } } } }, "422": { "description": "Validation failed / update failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“‚ Campaigns" ], "summary": "Delete a campaign", "description": "Permanently delete a campaign (folder) from the workspace. Posts assigned to it are detached.", "operationId": "deleteCampaign", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "campaign_id", "in": "path", "description": "Campaign id", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "responses": { "200": { "description": "Campaign deleted", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Campaign deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to this workspace" } }, "type": "object" } } } }, "404": { "description": "Campaign not found in this workspace", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Campaign not found in this workspace" } }, "type": "object" } } } }, "422": { "description": "Delete failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Delete failed" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/posts/{post_id}/comments": { "get": { "tags": [ "πŸ’¬ Comments" ], "summary": "Fetch post comments", "description": "Retrieve a paginated list of comments for a specific post", "operationId": "fetchComments", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "post_id", "in": "path", "description": "Post/Plan ID", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890a" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "default": 1, "minimum": 1, "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "example": 20 } } ], "responses": { "200": { "description": "Comments retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Comments fetched successfully" }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 45 }, "last_page": { "type": "integer", "example": 3 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 20 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "66a1f2e4c8b9a1234567890a" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "66a1f2e4c8b9a1234567890a", "deprecated": true }, "comment": { "type": "string", "example": "Great post!" }, "is_note": { "type": "boolean", "example": false }, "mentioned_users": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "627a078300a7d866600e7d02" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "627a078300a7d866600e7d02", "deprecated": true }, "name": { "type": "string", "example": "John Doe" } }, "type": "object" } }, "author": { "properties": { "id": { "type": "string", "example": "627a078300a7d866600e7d02" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "627a078300a7d866600e7d02", "deprecated": true }, "name": { "type": "string", "example": "Jane Smith" }, "profile_picture": { "type": "string", "example": "https://example.com/avatar.jpg", "nullable": true } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-15T10:30:00.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-01-15T10:30:00.000000Z" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid" }, "404": { "description": "Post not found" }, "429": { "description": "Too many requests" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ’¬ Comments" ], "summary": "Add a comment to a post", "description": "Create a new comment or internal note on a post", "operationId": "addComment", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "post_id", "in": "path", "description": "Post/Plan ID", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "comment" ], "properties": { "comment": { "type": "string", "example": "This looks great, ready to publish!" }, "is_note": { "description": "True for internal note", "type": "boolean", "example": false }, "mentioned_users": { "description": "User IDs to mention", "type": "array", "items": { "type": "string" }, "example": [ "user456" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Comment created successfully" }, "data": { "properties": { "id": { "type": "string", "example": "66a1f2e4c8b9a1234567890a" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "66a1f2e4c8b9a1234567890a", "deprecated": true }, "comment": { "type": "string", "example": "Great post!" }, "is_note": { "type": "boolean", "example": false }, "mentioned_users": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "627a078300a7d866600e7d02" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "627a078300a7d866600e7d02", "deprecated": true }, "name": { "type": "string", "example": "John Doe" } }, "type": "object" } }, "author": { "properties": { "id": { "type": "string", "example": "627a078300a7d866600e7d02" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "627a078300a7d866600e7d02", "deprecated": true }, "name": { "type": "string", "example": "Jane Smith" }, "profile_picture": { "type": "string", "example": "https://example.com/avatar.jpg", "nullable": true } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-15T10:30:00.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-01-15T10:30:00.000000Z" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request or validation error" }, "401": { "description": "Unauthorized - API key missing or invalid" }, "404": { "description": "Post not found" }, "429": { "description": "Too many requests" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/platforms": { "get": { "tags": [ "πŸ”— Account Connection" ], "summary": "List platforms available for account connection", "description": "Returns supported platforms, their connection method, required fields, and the endpoint to use for each connection flow.", "operationId": "listConnectPlatforms", "responses": { "200": { "description": "Platforms retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Platforms available for connection via the API." }, "data": { "type": "array", "items": { "properties": { "platform": { "type": "string", "example": "facebook" }, "display_name": { "type": "string", "example": "Facebook" }, "connection_method": { "type": "string", "enum": [ "oauth", "credentials", "manual" ], "example": "oauth" }, "endpoint": { "type": "string", "example": "POST /api/v1/workspaces/{workspace_id}/connect/facebook" }, "has_account_selection": { "type": "boolean", "example": true }, "account_types": { "type": "array", "items": { "type": "string", "example": "page" } }, "description": { "type": "string", "example": "Connect Facebook pages and profiles. Requires browser-based authorization." }, "required_fields": { "type": "object", "nullable": true, "additionalProperties": { "type": "string", "example": "Your Bluesky handle (e.g. yourname.bsky.social)" } } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/connect/{platform}": { "post": { "tags": [ "πŸ”— Account Connection" ], "summary": "Initiate an OAuth account connection or reconnection flow", "description": "Generates a one-time authorization URL for OAuth-based social account connection. Use process=connect for new accounts and process=reconnect (with account_id) to refresh an expired or invalid account.", "operationId": "connectAccount", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "platform", "in": "path", "description": "OAuth platform key", "required": true, "schema": { "type": "string", "enum": [ "facebook", "facebook-profile", "instagram", "instagram-via-facebook", "twitter", "linkedin", "pinterest", "tiktok", "youtube", "threads", "gmb", "tumblr" ], "example": "facebook" } }, { "name": "process", "in": "query", "description": "`connect` to add a new account, `reconnect` to refresh an expired/invalid account", "required": true, "schema": { "type": "string", "enum": [ "connect", "reconnect" ], "example": "connect" } }, { "name": "account_id", "in": "query", "description": "Required only when process=reconnect β€” the account ID to refresh", "required": false, "schema": { "type": "string" } }, { "name": "return_url", "in": "query", "description": "Optional URL the user is sent back to from the browser after finishing the connect flow. Must be an absolute http(s) URL.", "required": false, "schema": { "type": "string", "format": "uri", "maxLength": 2048, "example": "https://yourapp.com/settings/integrations" } } ], "responses": { "200": { "description": "Authorization URL generated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Authorization URL generated. Open this URL in a browser to connect your Facebook account." }, "data": { "properties": { "authorization_url": { "type": "string", "format": "uri", "example": "https://www.facebook.com/v18.0/dialog/oauth?client_id=...&state=..." }, "session_id": { "type": "string", "example": "cs_sess_abc123def456" }, "platform": { "type": "string", "example": "facebook" }, "process": { "type": "string", "example": "connect" }, "account_name": { "description": "Present only when process=reconnect", "type": "string", "example": "My Business Page" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-04-16T17:30:00Z" }, "next_steps": { "type": "array", "items": { "type": "string", "example": "Open the authorization_url in a web browser." } }, "security": { "properties": { "expires_in_minutes": { "type": "integer", "example": 30 }, "single_use": { "type": "boolean", "example": true }, "warning": { "type": "string", "example": "Do not share this URL. It grants one-time access to connect an account to your workspace." } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Account not found (reconnect only)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Account '610a1e660cb41530ca40d372' not found in this workspace, or it does not belong to the 'facebook' platform." }, "error_code": { "type": "string", "example": "ACCOUNT_NOT_FOUND" } }, "type": "object" } } } }, "422": { "description": "Validation error, invalid platform, wrong endpoint, or account already active", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The process field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/content-categories": { "get": { "tags": [ "πŸ“ Content Categories" ], "summary": "Get content categories for a workspace", "description": "Retrieve list of content categories for a specific workspace with resolved social account information. Global categories are excluded.", "operationId": "fetchContentCategories", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (max: 100)", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "example": 10 } }, { "name": "search", "in": "query", "description": "Search term(s) to filter categories by name. Comma-separated for multiple terms (e.g., 'marketing,sales')", "required": false, "schema": { "type": "string", "example": "marketing" } } ], "responses": { "200": { "description": "Content categories retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Content categories retrieved successfully." }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 25 }, "last_page": { "type": "integer", "example": 3 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 10 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "625d06734ceb636c2f5e7743", "deprecated": true }, "name": { "type": "string", "example": "My Category" }, "color": { "type": "string", "example": "color_15" }, "state": { "type": "string", "example": "active" }, "accounts": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "106939092115395" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "106939092115395", "deprecated": true }, "platform": { "type": "string", "example": "facebook" }, "name": { "type": "string", "example": "My Facebook Page" } }, "type": "object" } }, "slots_count": { "type": "integer", "example": 5 }, "posts_count": { "type": "integer", "example": 10 }, "color_code": { "type": "string", "example": "#544c72" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Workspace not found or access denied", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found or access denied" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“ Content Categories" ], "summary": "Create a content category", "description": "Create a new content category in the specified workspace. `accounts` is a single flat list of social account IDs mixed across platforms β€” the same values returned under `accounts[]` by the list endpoint β€” so a list response can be round-tripped straight back into a create request. Categories created here are always workspace-local; global categories are managed separately.", "operationId": "createContentCategory", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "color" ], "properties": { "name": { "type": "string", "maxLength": 100, "example": "Product Launch" }, "color": { "type": "string", "enum": [ "color_1", "color_2", "color_3", "color_4", "color_5", "color_6", "color_7", "color_8", "color_9", "color_10", "color_11", "color_12", "color_13", "color_14", "color_15", "color_16", "color_17", "color_18", "color_19", "color_20" ], "example": "color_3" }, "allowed_member_ids": { "description": "Restrict the category to these workspace members. Omit to leave it visible to everyone.", "type": "array", "items": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } }, "accounts": { "description": "Social account IDs to attach, mixed across platforms.", "type": "array", "items": { "type": "string", "example": "106939092115395" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Content category created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryCreated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryAccessDenied" } } } }, "422": { "description": "Validation failed (`VALIDATION_ERROR`), an account ID is not valid for this workspace (`CONTENT_CATEGORY_INVALID_ACCOUNT`), or the create failed (`CONTENT_CATEGORY_CREATE_FAILED`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContentCategoryValidationError" }, { "$ref": "#/components/schemas/ContentCategoryWriteRejected" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/content-categories/{category_id}": { "get": { "tags": [ "πŸ“ Content Categories" ], "summary": "Get a single content category", "description": "Retrieve one content category with its resolved social accounts AND its full weekly posting schedule, so a caller does not need a second request to understand when the category publishes.", "operationId": "fetchContentCategory", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "category_id", "in": "path", "description": "Content category id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } ], "responses": { "200": { "description": "Content category retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryFetched" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUnauthorized" } } } }, "403": { "description": "No access to workspace, or no access to this content category (`CONTENT_CATEGORY_ACCESS_DENIED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryAccessDenied" } } } }, "404": { "description": "Content category not found in this workspace (`CONTENT_CATEGORY_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryNotFound" } } } }, "422": { "description": "The target is a global category copy (`CONTENT_CATEGORY_IS_GLOBAL`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryIsGlobal" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "πŸ“ Content Categories" ], "summary": "Update a content category", "description": "Partially update a content category. Fields that are not provided keep their current values. Providing `accounts` REPLACES the category's entire account list across every platform; omit it to leave the existing accounts untouched. Global categories cannot be modified through this endpoint.", "operationId": "updateContentCategory", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "category_id", "in": "path", "description": "Content category id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 100, "example": "Product Launch 2026" }, "color": { "type": "string", "enum": [ "color_1", "color_2", "color_3", "color_4", "color_5", "color_6", "color_7", "color_8", "color_9", "color_10", "color_11", "color_12", "color_13", "color_14", "color_15", "color_16", "color_17", "color_18", "color_19", "color_20" ], "example": "color_5" }, "allowed_member_ids": { "type": "array", "items": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } }, "accounts": { "description": "Replaces the full account list across all platforms.", "type": "array", "items": { "type": "string", "example": "106939092115395" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Content category updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUpdated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUnauthorized" } } } }, "403": { "description": "No access to workspace, or no access to this content category (`CONTENT_CATEGORY_ACCESS_DENIED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryAccessDenied" } } } }, "404": { "description": "Content category not found in this workspace (`CONTENT_CATEGORY_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryNotFound" } } } }, "422": { "description": "Validation failed (`VALIDATION_ERROR`), the target is a global category (`CONTENT_CATEGORY_IS_GLOBAL`), an account ID is not valid for this workspace (`CONTENT_CATEGORY_INVALID_ACCOUNT`), or the update failed (`CONTENT_CATEGORY_UPDATE_FAILED`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContentCategoryValidationError" }, { "$ref": "#/components/schemas/ContentCategoryWriteRejected" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“ Content Categories" ], "summary": "Delete a content category", "description": "Permanently delete a content category. Its weekly posting slots and per-member access entries are removed with it. Posts already scheduled against the category are NOT deleted and keep their `content_category_id`. Global categories cannot be deleted through this endpoint.", "operationId": "deleteContentCategory", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "category_id", "in": "path", "description": "Content category id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } ], "responses": { "200": { "description": "Content category deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryDeleted" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUnauthorized" } } } }, "403": { "description": "No access to workspace, or no access to this content category (`CONTENT_CATEGORY_ACCESS_DENIED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryAccessDenied" } } } }, "404": { "description": "Content category not found in this workspace (`CONTENT_CATEGORY_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryNotFound" } } } }, "422": { "description": "The target is a global category (`CONTENT_CATEGORY_IS_GLOBAL`) or the delete failed (`CONTENT_CATEGORY_DELETE_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryWriteRejected" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/content-categories/{category_id}/shuffle": { "post": { "tags": [ "πŸ“ Content Categories" ], "summary": "Shuffle a category's queued posts", "description": "Randomly reassign the execution times already held by this category's upcoming posts among those same posts. The set of times is unchanged β€” only which post occupies which time moves β€” so the publishing cadence stays exactly as configured. Only scheduled and queued posts are affected; published, failed and draft posts are untouched.", "operationId": "shuffleContentCategoryPosts", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "category_id", "in": "path", "description": "Content category id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } ], "responses": { "200": { "description": "Queued posts shuffled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryShuffled" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUnauthorized" } } } }, "403": { "description": "No access to workspace, or no access to this content category (`CONTENT_CATEGORY_ACCESS_DENIED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryAccessDenied" } } } }, "404": { "description": "Content category not found in this workspace (`CONTENT_CATEGORY_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryNotFound" } } } }, "422": { "description": "The target is a global category copy (`CONTENT_CATEGORY_IS_GLOBAL`), or the shuffle failed (`CONTENT_CATEGORY_SHUFFLE_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryWriteRejected" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/content-categories/{category_id}/slots": { "get": { "tags": [ "πŸ—“οΈ Content Category Slots" ], "summary": "List a category's posting slots", "description": "Retrieve every weekly posting slot on a content category, ordered by period then hour. Times are 12-hour: `hour` 0-11 plus an AM/PM `period`. `weekday_sorting` is the day's index with Sunday as 0.", "operationId": "fetchContentCategorySlots", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "category_id", "in": "path", "description": "Content category id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } ], "responses": { "200": { "description": "Slots retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategorySlotList" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUnauthorized" } } } }, "403": { "description": "No access to workspace, or no access to this content category (`CONTENT_CATEGORY_ACCESS_DENIED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryAccessDenied" } } } }, "404": { "description": "Content category not found in this workspace (`CONTENT_CATEGORY_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryNotFound" } } } }, "422": { "description": "The category is a global copy (`CONTENT_CATEGORY_IS_GLOBAL`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryIsGlobal" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ—“οΈ Content Category Slots" ], "summary": "Add a posting slot to a category", "description": "Create one weekly posting slot. Times are 12-hour: pass `hour` 0-12 with an AM/PM `period` β€” 12 is normalised to 0, so hour 12 with period AM is midnight and hour 12 with period PM is noon. Adding a slot does not reshuffle content already queued on the category: every occurrence of the new slot that falls before the last scheduled post is recorded as skipped, so the slot starts taking effect after that post.", "operationId": "createContentCategorySlot", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "category_id", "in": "path", "description": "Content category id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "day", "hour", "minute", "period" ], "properties": { "day": { "type": "string", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "example": "monday" }, "hour": { "description": "12-hour clock. 12 is normalised to 0.", "type": "integer", "maximum": 12, "minimum": 0, "example": 9 }, "minute": { "type": "integer", "maximum": 59, "minimum": 0, "example": 30 }, "period": { "type": "string", "enum": [ "AM", "PM" ], "example": "AM" } }, "type": "object" } } } }, "responses": { "201": { "description": "Slot created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategorySlotCreated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUnauthorized" } } } }, "403": { "description": "No access to workspace, or no access to this content category (`CONTENT_CATEGORY_ACCESS_DENIED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryAccessDenied" } } } }, "404": { "description": "Content category not found in this workspace (`CONTENT_CATEGORY_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryNotFound" } } } }, "422": { "description": "Validation failed (`VALIDATION_ERROR`), the category is a global copy (`CONTENT_CATEGORY_IS_GLOBAL`), the same day and time already has a slot (`CONTENT_CATEGORY_SLOT_DUPLICATE`), or the create failed (`CONTENT_CATEGORY_SLOT_CREATE_FAILED`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContentCategorySlotValidationError" }, { "$ref": "#/components/schemas/ContentCategorySlotRejected" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/content-categories/{category_id}/slots/{slot_id}": { "put": { "tags": [ "πŸ—“οΈ Content Category Slots" ], "summary": "Update a posting slot's day or time", "description": "Partially update a slot β€” anything you omit keeps its current value. A slot cannot be moved to a different category here; delete it and create it on the target category instead. Unlike creating a slot, editing one records no skip markers for the new time, matching the internal behaviour.", "operationId": "updateContentCategorySlot", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "category_id", "in": "path", "description": "Content category id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } }, { "name": "slot_id", "in": "path", "description": "Slot id", "required": true, "schema": { "type": "string", "example": "66c3d1a2b4e5f6789012345a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "day": { "type": "string", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "example": "friday" }, "hour": { "type": "integer", "maximum": 12, "minimum": 0, "example": 5 }, "minute": { "type": "integer", "maximum": 59, "minimum": 0, "example": 45 }, "period": { "type": "string", "enum": [ "AM", "PM" ], "example": "PM" } }, "type": "object" } } } }, "responses": { "200": { "description": "Slot updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategorySlotUpdated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUnauthorized" } } } }, "403": { "description": "No access to workspace, or no access to this content category (`CONTENT_CATEGORY_ACCESS_DENIED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryAccessDenied" } } } }, "404": { "description": "Category not found (`CONTENT_CATEGORY_NOT_FOUND`), or the slot does not exist on this category (`CONTENT_CATEGORY_SLOT_NOT_FOUND`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContentCategoryNotFound" }, { "$ref": "#/components/schemas/ContentCategorySlotNotFound" } ] } } } }, "422": { "description": "Validation failed (`VALIDATION_ERROR`), the category is a global copy (`CONTENT_CATEGORY_IS_GLOBAL`), the resulting day and time collides with another slot (`CONTENT_CATEGORY_SLOT_DUPLICATE`), or the update failed (`CONTENT_CATEGORY_SLOT_UPDATE_FAILED`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContentCategorySlotValidationError" }, { "$ref": "#/components/schemas/ContentCategorySlotRejected" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ—“οΈ Content Category Slots" ], "summary": "Delete a posting slot", "description": "Remove one weekly posting slot from a category. The skip markers this slot recorded are purged with it, so nothing lingers on the category; markers belonging to other slots are left alone.", "operationId": "deleteContentCategorySlot", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "category_id", "in": "path", "description": "Content category id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } }, { "name": "slot_id", "in": "path", "description": "Slot id", "required": true, "schema": { "type": "string", "example": "66c3d1a2b4e5f6789012345a" } } ], "responses": { "200": { "description": "Slot deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategorySlotDeleted" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUnauthorized" } } } }, "403": { "description": "No access to workspace, or no access to this content category (`CONTENT_CATEGORY_ACCESS_DENIED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryAccessDenied" } } } }, "404": { "description": "Category not found (`CONTENT_CATEGORY_NOT_FOUND`), or the slot does not exist on this category (`CONTENT_CATEGORY_SLOT_NOT_FOUND`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContentCategoryNotFound" }, { "$ref": "#/components/schemas/ContentCategorySlotNotFound" } ] } } } }, "422": { "description": "The category is a global copy (`CONTENT_CATEGORY_IS_GLOBAL`) or the delete failed (`CONTENT_CATEGORY_SLOT_DELETE_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategorySlotRejected" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/content-categories/{category_id}/slots/next": { "get": { "tags": [ "πŸ—“οΈ Content Category Slots" ], "summary": "Get a category's next available posting slot", "description": "Answer when a post queued into this category right now would publish. The time is returned in the workspace's own timezone, with that timezone named alongside it so a caller never has to guess. Returns a null time when the category has no slots, or none upcoming.", "operationId": "fetchContentCategoryNextSlot", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "category_id", "in": "path", "description": "Content category id", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } }, { "name": "post_id", "in": "query", "description": "Ask where an EXISTING post already sits instead. When that post is queued into this category and still upcoming, its own scheduled time is returned with `scheduled: true`.", "required": false, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890c" } } ], "responses": { "200": { "description": "Next slot resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryNextSlot" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryUnauthorized" } } } }, "403": { "description": "No access to workspace, or no access to this content category (`CONTENT_CATEGORY_ACCESS_DENIED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryAccessDenied" } } } }, "404": { "description": "Content category not found in this workspace (`CONTENT_CATEGORY_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryNotFound" } } } }, "422": { "description": "The category is a global copy (`CONTENT_CATEGORY_IS_GLOBAL`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryIsGlobal" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCategoryRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/facebook/text-backgrounds": { "get": { "tags": [ "πŸ“ Posts" ], "summary": "List Facebook text-post background presets", "description": "Returns the full list of Facebook colored-background preset IDs accepted by `facebook_options.facebook_background_id` on POST /api/v1/workspaces/{workspace_id}/posts. Backgrounds only apply to plain text posts (no media, no link).", "operationId": "listFacebookTextBackgrounds", "responses": { "200": { "description": "Text backgrounds retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Facebook text backgrounds retrieved successfully. Use the returned `id` as `facebook_background_id` when creating a Facebook post." }, "data": { "type": "array", "items": { "properties": { "id": { "description": "Preset ID to pass as facebook_options.facebook_background_id", "type": "string", "example": "106018623298955" }, "type": { "type": "string", "enum": [ "solid", "gradient", "image" ], "example": "solid" }, "background_color": { "description": "CSS background value. Empty string for image-type presets.", "type": "string", "example": "rgb(198, 0, 255)" }, "color": { "description": "Text color that pairs with the background.", "type": "string", "example": "#ffffff" }, "description": { "type": "string", "example": "Solid purple" }, "category": { "type": "string", "enum": [ "ranked", "popular", "new", "more" ], "example": "popular" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/conversations/{conversation_id}/messages": { "get": { "tags": [ "πŸ“₯ Inbox: Messages" ], "summary": "List messages in a conversation", "operationId": "inboxConversationMessages", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversation_id", "in": "path", "description": "The conversation element's element_id from /elements/search (provider thread id, e.g. t_2254239152032015). Its element_ref is also accepted.", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 200 } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Messages retrieved, ordered by time", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "messages": { "type": "array", "items": { "type": "object" } }, "total_messages": { "description": "Collection-wide count (`total` is page-local)", "type": "integer" }, "page": { "description": "Echoes the requested page", "type": "integer" }, "page_count": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Not a member of this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`." }, "502": { "description": "Inbox service unavailable" } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“₯ Inbox: Messages" ], "summary": "Send a DM (text, or media when a file is attached)", "operationId": "inboxSendMessage", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversation_id", "in": "path", "description": "The conversation element's element_id from /elements/search (provider thread id, e.g. t_2254239152032015). Its element_ref is also accepted.", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "De-duplicates a retry. Protects sequential retries; concurrent duplicate sends may both be delivered.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "platform_type", "platform_id" ], "properties": { "platform_type": { "type": "string", "enum": [ "facebook", "instagram" ] }, "platform_id": { "type": "string" }, "message": { "type": "string" }, "file": { "description": "8 MB image / 25 MB video, validated by file signature", "type": "string", "format": "binary" }, "file_type": { "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "sent_message": { "properties": { "resource_type": { "type": "string", "example": "message" }, "external_id": { "description": "Platform id, null when the platform returned none", "type": "string" }, "id_status": { "type": "string", "enum": [ "resolved", "unavailable" ] } }, "type": "object" } }, "type": "object" } } } }, "409": { "description": "Idempotency conflict, or an outcome that cannot be determined" }, "422": { "description": "Validation error, or recipient_id does not match the conversation" }, "503": { "description": "Idempotency store unavailable β€” retry" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/posts/{post_id}/comments": { "get": { "tags": [ "πŸ“₯ Inbox: Comments" ], "summary": "List a post's comments (threaded)", "operationId": "inboxPostComments", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 200 } } ], "responses": { "200": { "description": "Comments retrieved. Replies are nested under each thread's `children`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "comments": { "type": "array", "items": { "type": "object" } }, "total_comment_count": { "description": "ALL comments including replies", "type": "integer" }, "total_threads": { "description": "Top-level threads β€” the pagination universe", "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“₯ Inbox: Comments" ], "summary": "Post a comment, reply, or Facebook private reply", "operationId": "inboxSendComment", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "platform_type", "platform_id" ], "properties": { "platform_type": { "type": "string" }, "platform_id": { "type": "string" }, "message": { "type": "string" }, "comment_id": { "description": "Set to reply to a specific comment", "type": "string" }, "is_private_reply": { "description": "Facebook: creates a MESSAGE, not a comment", "type": "boolean" }, "attachment_file": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Posted. `sent_comment.resource_type` is `comment`, or `message` for a private reply.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "sent_comment": { "type": "object" } }, "type": "object" } } } }, "409": { "description": "Idempotency conflict" }, "422": { "description": "Validation error" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/conversations/{conversation_id}/notes": { "get": { "tags": [ "πŸ“₯ Inbox: Messages" ], "summary": "List internal notes on a conversation", "operationId": "inboxConversationNotes", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversation_id", "in": "path", "description": "The conversation element's element_id from /elements/search (provider thread id, e.g. t_2254239152032015). Its element_ref is also accepted.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notes retrieved" }, "401": { "description": "Unauthorized" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“₯ Inbox: Messages" ], "summary": "Add an internal note", "operationId": "inboxAddNote", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversation_id", "in": "path", "description": "The conversation element's element_id from /elements/search (provider thread id, e.g. t_2254239152032015). Its element_ref is also accepted.", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "message", "platform_type", "platform_id" ], "properties": { "message": { "type": "string" }, "platform_type": { "type": "string" }, "platform_id": { "type": "string" }, "mentioned_users": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Note added" }, "422": { "description": "Validation error" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/comments/{comment_id}/hidden": { "put": { "tags": [ "πŸ“₯ Inbox: Comments" ], "summary": "Hide a comment (idempotent)", "operationId": "inboxHideComment", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment hidden" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“₯ Inbox: Comments" ], "summary": "Unhide a comment (idempotent)", "operationId": "inboxUnhideComment", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform_type", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "platform_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment unhidden" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/comments/{comment_id}/like": { "put": { "tags": [ "πŸ“₯ Inbox: Comments" ], "summary": "Like a comment (idempotent, Facebook)", "operationId": "inboxLikeComment", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment liked" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“₯ Inbox: Comments" ], "summary": "Unlike a comment (idempotent, Facebook)", "operationId": "inboxUnlikeComment", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment unliked" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/comments/{comment_id}": { "delete": { "tags": [ "πŸ“₯ Inbox: Comments" ], "summary": "Delete a comment", "operationId": "inboxDeleteComment", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform_type", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "platform_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "comment_urn", "in": "query", "description": "Required for LinkedIn", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment deleted" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/reviews/{review_id}/reply": { "put": { "tags": [ "πŸ“₯ Inbox: Reviews" ], "summary": "Add or replace a review reply (upsert)", "operationId": "inboxReviewReply", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "review_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "platform_id", "review_reply" ], "properties": { "platform_id": { "type": "string" }, "review_reply": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reply saved" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“₯ Inbox: Reviews" ], "summary": "Delete a review reply", "operationId": "inboxDeleteReviewReply", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "review_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reply deleted" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/messages/{message_id}/bookmark": { "put": { "tags": [ "πŸ“₯ Inbox: Messages" ], "summary": "Star a message (idempotent)", "operationId": "inboxBookmarkMessage", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Starred" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“₯ Inbox: Messages" ], "summary": "Unstar a message (idempotent)", "operationId": "inboxUnbookmarkMessage", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Unstarred" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/messages/{message_id}": { "delete": { "tags": [ "πŸ“₯ Inbox: Messages" ], "summary": "Delete a message (soft)", "operationId": "inboxDeleteMessage", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" }, "404": { "description": "Message not found in this workspace" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/elements/search": { "post": { "tags": [ "πŸ“₯ Inbox: Items" ], "summary": "Search inbox elements", "operationId": "inboxElementsSearch", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "inbox_types": { "description": "conversation, post, review", "type": "array", "items": { "type": "string" } }, "action": { "description": "Status filter, e.g. all, marked_done, archived, assigned", "type": "string" }, "page": { "type": "integer", "default": 1 }, "limit": { "type": "integer", "default": 20, "maximum": 200 }, "search_term": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "all_channels": { "description": "Platform => account ids", "type": "object" }, "targeted_element": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Elements retrieved. An empty result set is a successful empty read, not a 404.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "elements": { "type": "array", "items": { "type": "object" } }, "total_count": { "type": "integer", "example": 42 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 3 }, "limit": { "type": "integer", "example": 20 } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Not a member of this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`." }, "422": { "description": "Validation error" }, "429": { "description": "Too many requests" }, "502": { "description": "Inbox service unavailable" } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/elements/summary": { "post": { "tags": [ "πŸ“₯ Inbox: Items" ], "summary": "Inbox counts per bucket", "operationId": "inboxElementsSummary", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "inbox_types": { "type": "array", "items": { "type": "string" } }, "all_channels": { "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Counts retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "element_counts": { "type": "object", "example": { "ALL": 42, "UNASSIGNED": 10, "ASSIGNED": 8, "MINE": 3, "MARKED_AS_DONE": 5, "ARCHIVED": 2 } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Not a member of this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`." }, "422": { "description": "Validation error" }, "429": { "description": "Too many requests" }, "502": { "description": "Inbox service unavailable" } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/conversations/{conversation_id}/bookmarks": { "get": { "tags": [ "πŸ“₯ Inbox: Messages" ], "summary": "List starred messages in a conversation", "operationId": "inboxConversationBookmarks", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversation_id", "in": "path", "description": "The conversation element's element_id from /elements/search (provider thread id, e.g. t_2254239152032015). Its element_ref is also accepted.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bookmarks retrieved" }, "401": { "description": "Unauthorized" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/tags": { "get": { "tags": [ "πŸ“₯ Inbox: Tags" ], "summary": "List the workspace's inbox tags", "operationId": "inboxTagsIndex", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tags retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "tags": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“₯ Inbox: Tags" ], "summary": "Create a tag", "operationId": "inboxTagCreate", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "tag_name", "tag_color" ], "properties": { "tag_name": { "type": "string", "maxLength": 50 }, "tag_color": { "type": "string", "example": "#FF0000" } }, "type": "object" } } } }, "responses": { "201": { "description": "Tag created" }, "422": { "description": "Validation error" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“₯ Inbox: Tags" ], "summary": "Delete tags (bulk)", "operationId": "inboxTagsDelete", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "tag_ids" ], "properties": { "tag_ids": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Tags deleted" }, "404": { "description": "No matching tag in this workspace" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/elements/{element_ref}/contact": { "get": { "tags": [ "πŸ“₯ Inbox: Items" ], "summary": "Read an element's contact profile", "operationId": "inboxElementContact", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "element_ref", "in": "path", "description": "Canonical element ref, or the provider element id", "required": true, "schema": { "type": "string" } }, { "name": "platform_id", "in": "query", "description": "Narrows resolution when a provider element id exists under two accounts", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact retrieved. NOTE: this returns end-customer personal data (email, phone).", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "contact": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Element not found in this workspace, or it has no contact record" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "patch": { "tags": [ "πŸ“₯ Inbox: Items" ], "summary": "Update an element's contact profile", "operationId": "inboxElementUpdateContact", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "element_ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "platform_id" ], "properties": { "platform_id": { "description": "Connected account the contact belongs to. SIM resolves the record by workspace + account + element, so a provider element_id shared by two accounts cannot resolve ambiguously.", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Contact updated. This applies to EVERY element for this contact on this account in the workspace β€” a contact is a person, not a per-element attribute. `updated_count` reports how many.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "updated_count": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "404": { "description": "Element not found in this workspace" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/elements": { "patch": { "tags": [ "πŸ“₯ Inbox: Items" ], "summary": "Bulk element state change (done / pending / archive / assign)", "operationId": "inboxElementsBulkUpdate", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "element_refs" ], "properties": { "element_refs": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "status": { "type": "string", "enum": [ "done", "pending" ] }, "archived": { "type": "boolean" }, "assigned": { "type": "boolean" }, "assigned_to": { "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "All elements updated" }, "207": { "description": "Partial success β€” see missing_ids" }, "422": { "description": "Validation error, or not exactly one operation supplied" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/elements/{element_ref}/read": { "put": { "tags": [ "πŸ“₯ Inbox: Items" ], "summary": "Mark an element read (idempotent)", "operationId": "inboxElementMarkRead", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "element_ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Marked read. Calling again is a no-op and still succeeds." }, "404": { "description": "Element not found in this workspace" }, "422": { "description": "element_type does not match the stored element" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/elements/{element_ref}/tags": { "post": { "tags": [ "πŸ“₯ Inbox: Items" ], "summary": "Attach tags to an element", "operationId": "inboxElementAddTags", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "element_ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "tags", "platform_id", "inbox_type" ], "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "platform_id": { "description": "Connected account the element belongs to", "type": "string" }, "inbox_type": { "type": "string", "enum": [ "conversation", "post", "review" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Tags attached" }, "422": { "description": "A tag id does not belong to this workspace" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/elements/{element_ref}/tags/{tag_id}": { "delete": { "tags": [ "πŸ“₯ Inbox: Items" ], "summary": "Detach a tag from an element", "operationId": "inboxElementRemoveTag", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "element_ref", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "inbox_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "conversation", "post", "review" ] } } ], "responses": { "200": { "description": "Tag detached" }, "422": { "description": "Validation error" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/tags/{tag_id}": { "patch": { "tags": [ "πŸ“₯ Inbox: Tags" ], "summary": "Rename or recolour a tag", "operationId": "inboxTagUpdate", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "tag_name": { "type": "string" }, "tag_color": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tag updated" }, "404": { "description": "Tag not found in this workspace" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/inbox/tags/merge": { "post": { "tags": [ "πŸ“₯ Inbox: Tags" ], "summary": "Merge tags into a new one", "operationId": "inboxTagsMerge", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "tag_name", "tag_color", "tag_ids" ], "properties": { "tag_name": { "type": "string" }, "tag_color": { "type": "string" }, "tag_ids": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Tags merged" }, "422": { "description": "Validation error" }, "502": { "description": "Inbox service unavailable" }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `FEATURE_NOT_IN_PLAN`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/labels": { "get": { "tags": [ "🏷️ Labels" ], "summary": "Get labels for a workspace", "description": "Retrieve paginated list of labels for a specific workspace, sorted alphabetically by name.", "operationId": "fetchLabels", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (max: 100)", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "example": 10 } }, { "name": "search", "in": "query", "description": "Search term to filter labels by name (case-insensitive partial match)", "required": false, "schema": { "type": "string", "example": "marketing" } } ], "responses": { "200": { "description": "Labels retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Labels retrieved successfully" }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 25 }, "last_page": { "type": "integer", "example": 3 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 10 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "625d06734ceb636c2f5e7743", "deprecated": true }, "name": { "type": "string", "example": "Urgent" }, "color": { "type": "string", "example": "color_1" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "🏷️ Labels" ], "summary": "Create a label", "description": "Create a new label in the specified workspace. Color must be one of color_1..color_20.", "operationId": "createLabel", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "color" ], "properties": { "name": { "type": "string", "maxLength": 100, "example": "Urgent" }, "color": { "type": "string", "enum": [ "color_1", "color_2", "color_3", "color_4", "color_5", "color_6", "color_7", "color_8", "color_9", "color_10", "color_11", "color_12", "color_13", "color_14", "color_15", "color_16", "color_17", "color_18", "color_19", "color_20" ], "example": "color_2" } }, "type": "object" } } } }, "responses": { "201": { "description": "Label created", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Label created successfully. Use the returned `id` in `labels[]` when creating a post, or to update or delete this label." }, "data": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "625d06734ceb636c2f5e7743", "deprecated": true }, "name": { "type": "string", "example": "Urgent" }, "color": { "type": "string", "example": "color_2" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`." }, "422": { "description": "Validation failed" }, "429": { "description": "Too Many Requests - Rate limit exceeded" } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/labels/{label_id}": { "put": { "tags": [ "🏷️ Labels" ], "summary": "Update a label", "description": "Update a label's name and/or color. Partial updates allowed β€” only the fields provided are changed.", "operationId": "updateLabel", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "label_id", "in": "path", "description": "Label id", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 100, "example": "High priority" }, "color": { "type": "string", "enum": [ "color_1", "color_2", "color_3", "color_4", "color_5", "color_6", "color_7", "color_8", "color_9", "color_10", "color_11", "color_12", "color_13", "color_14", "color_15", "color_16", "color_17", "color_18", "color_19", "color_20" ], "example": "color_4" } }, "type": "object" } } } }, "responses": { "200": { "description": "Label updated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Label updated successfully" }, "data": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "625d06734ceb636c2f5e7743", "deprecated": true }, "name": { "type": "string", "example": "High priority" }, "color": { "type": "string", "example": "color_4" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to this workspace" } }, "type": "object" } } } }, "404": { "description": "Label not found in this workspace", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Label not found in this workspace" } }, "type": "object" } } } }, "422": { "description": "Validation failed / update failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "🏷️ Labels" ], "summary": "Delete a label", "description": "Permanently delete a label from the workspace.", "operationId": "deleteLabel", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "label_id", "in": "path", "description": "Label id", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "responses": { "200": { "description": "Label deleted", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Label deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to this workspace" } }, "type": "object" } } } }, "404": { "description": "Label not found in this workspace", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Label not found in this workspace" } }, "type": "object" } } } }, "422": { "description": "Delete failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Delete failed" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/limits": { "get": { "tags": [ "πŸ“Š Limits & Usage" ], "summary": "Get plan limits and current usage", "description": "Read every metered entitlement for a workspace with what has been used, what the plan allows, and whether it applies β€” the same figures the billing screen shows for the same workspace. Addons and stackable multipliers are already folded into each limit, so the numbers are the customer's real entitlement rather than their base plan. Read it before a large batch instead of discovering a limit mid-run. The request-rate ceiling is not included β€” it is published on every response as the standard X-RateLimit-Limit and X-RateLimit-Remaining headers.", "operationId": "getWorkspaceLimits", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Limits and usage retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitsResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsForbidden" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsWorkspaceNotFound" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/media": { "get": { "tags": [ "πŸ“ Content Library" ], "summary": "List media assets", "description": "Retrieve a paginated list of media assets for a workspace with filtering, search, and sort options.", "operationId": "listMedia", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "default": 1, "minimum": 1, "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (max: 100)", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "example": 20 } }, { "name": "type", "in": "query", "description": "Filter by media type", "schema": { "type": "string", "enum": [ "images", "videos" ], "example": "images" } }, { "name": "search", "in": "query", "description": "Search media by name (case-insensitive partial match)", "schema": { "type": "string", "maxLength": 255, "example": "banner" } }, { "name": "sort", "in": "query", "description": "Sort order", "schema": { "type": "string", "default": "recent", "enum": [ "recent", "oldest", "size", "a2z", "z2a" ] } }, { "name": "archived", "in": "query", "description": "Set true to list archived media instead of active media. Defaults to false.", "required": false, "schema": { "type": "boolean", "example": false } }, { "name": "folder_id", "in": "query", "description": "Restrict the listing to one folder. Must belong to this workspace (or its shared tree) β€” any other id returns 404 FOLDER_NOT_FOUND.", "required": false, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7799" } } ], "responses": { "200": { "description": "Media retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Media retrieved successfully." }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 150 }, "last_page": { "type": "integer", "example": 8 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 20 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "625d06734ceb636c2f5e7743", "deprecated": true }, "name": { "type": "string", "example": "banner.jpg" }, "url": { "type": "string", "example": "https://storage.googleapis.com/.../banner.jpg" }, "mime_type": { "type": "string", "example": "image/jpeg" }, "extension": { "type": "string", "example": "jpg" }, "size": { "type": "integer", "example": 245760 }, "type": { "type": "string", "enum": [ "image", "video", "gif" ], "example": "image" }, "folder_id": { "type": "string", "nullable": true }, "is_processing": { "type": "boolean", "example": false }, "is_ai_generated": { "description": "True for media the assistant generated or imported. Drives the AI section of the Content Library.", "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time" }, "dimensions": { "properties": { "width": { "type": "integer", "example": 1920, "nullable": true }, "height": { "type": "integer", "example": 1080, "nullable": true } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaBadRequest" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "404": { "description": "folder_id does not belong to this workspace (FOLDER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaNotFound" } } } }, "422": { "description": "Query workspace_id contradicts the path segment (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaValidationError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“ Content Library" ], "summary": "Upload media", "description": "Upload a media file or import from URL into the workspace content library. Provide either a file or a URL, not both.", "operationId": "uploadMedia", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "Media file to upload (mutually exclusive with url)", "type": "string", "format": "binary" }, "url": { "description": "URL to import media from (mutually exclusive with file)", "type": "string", "format": "url", "example": "https://example.com/image.jpg" }, "folder_id": { "description": "Folder ID to upload into", "type": "string", "example": "625d06734ceb636c2f5e7743", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Media uploaded successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Media uploaded successfully. Use the returned `id` in `content.media.media_ids` when creating a post. If `is_processing` is true, wait and check GET /media before referencing it." }, "data": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "625d06734ceb636c2f5e7743", "deprecated": true }, "name": { "type": "string", "example": "photo.jpg" }, "url": { "type": "string", "example": "https://storage.googleapis.com/.../photo.jpg" }, "mime_type": { "type": "string", "example": "image/jpeg" }, "extension": { "type": "string", "example": "jpg" }, "size": { "type": "integer", "example": 245760 }, "type": { "type": "string", "enum": [ "image", "video", "gif" ], "example": "image" }, "folder_id": { "type": "string", "nullable": true }, "is_processing": { "type": "boolean", "example": false }, "is_ai_generated": { "description": "True for media the assistant generated or imported. Drives the AI section of the Content Library.", "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time" }, "dimensions": { "properties": { "width": { "type": "integer", "nullable": true }, "height": { "type": "integer", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or upload failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaBadRequest" } } } }, "422": { "description": "Query workspace_id contradicts the path segment (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaValidationError" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } }, "507": { "description": "The upload would exceed the workspace's media storage limit (MEDIA_STORAGE_LIMIT_EXCEEDED). Nothing is stored. Read GET /media/storage before uploading to avoid this.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Upload refused: it would exceed this workspace's media storage limit of 10.00 GB (10.00 GB currently used, 0 bytes available)." }, "error_code": { "type": "string", "example": "MEDIA_STORAGE_LIMIT_EXCEEDED" }, "context": { "properties": { "total_bytes": { "type": "integer", "format": "int64", "example": 10737418240 }, "used_bytes": { "type": "integer", "format": "int64", "example": 10737418240 }, "available_bytes": { "type": "integer", "format": "int64", "example": 0 }, "used_percentage": { "type": "number", "format": "float", "example": 100 } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccessDenied" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/media/{media_id}": { "delete": { "tags": [ "πŸ“ Content Library" ], "summary": "Delete media permanently", "description": "**Irreversible.** Permanently deletes the media file from the library and from cloud storage. If the media is attached to a post that has not published yet (scheduled, queued, or awaiting review), the call returns 422 REQUIRES_DELETE_CONFIRMATION and deletes nothing; resend with confirmed=true to proceed, or archive the media instead to keep those posts working.", "operationId": "deleteMedia", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } }, { "name": "confirmed", "in": "query", "description": "Set true to delete media that is used by posts which have not published yet", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Media deleted", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Media deleted permanently." }, "affected_scheduled_posts": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "404": { "description": "Media not found in this workspace (MEDIA_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaNotFound" } } } }, "422": { "description": "Confirmation required (REQUIRES_DELETE_CONFIRMATION)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This media is used by 2 scheduled post(s)..." }, "error_code": { "type": "string", "example": "REQUIRES_DELETE_CONFIRMATION" }, "context": { "properties": { "scheduled_post_count": { "type": "integer", "example": 2 }, "scheduled_post_ids": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/media/archive": { "post": { "tags": [ "πŸ“ Content Library" ], "summary": "Archive or unarchive media", "description": "Archiving hides media from the default library listing without deleting it β€” the safe alternative to deletion for media attached to posts that have not published yet. Set archived=false to restore items to their original folder. Reversible.", "operationId": "archiveMedia", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "media_ids", "archived" ], "properties": { "media_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "example": [ "625d06734ceb636c2f5e7743" ] }, "archived": { "description": "true archives, false restores", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Media archived or unarchived", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Media archived successfully." } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "404": { "description": "One or more media not found in this workspace (MEDIA_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaNotFound" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaValidationError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/media/move": { "post": { "tags": [ "πŸ“ Content Library" ], "summary": "Move media between folders", "description": "Moves the given media into a folder. Pass folder_id=null to move items to Uncategorized. Note that moving an archived item also restores it from the archive, matching the behaviour of the web app. Reversible.", "operationId": "moveMedia", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "media_ids" ], "properties": { "media_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "example": [ "625d06734ceb636c2f5e7743" ] }, "folder_id": { "description": "Destination folder; null moves to Uncategorized", "type": "string", "example": "625d06734ceb636c2f5e7799", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Media moved. Assets already in the destination are reported under `skipped` rather than failing the request, so a repeated call is a safe no-op.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Media moved successfully." }, "moved": { "description": "Assets whose folder actually changed", "type": "integer", "example": 1 }, "skipped": { "description": "Assets already in the destination folder", "type": "integer", "example": 0 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "404": { "description": "Media or destination folder not found (MEDIA_NOT_FOUND / FOLDER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaNotFound" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaValidationError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/media/storage": { "get": { "tags": [ "πŸ“ Content Library" ], "summary": "Get media storage limit and usage", "description": "Returns the media storage limit, current usage and remaining space for the workspace, so an integration can check for room before uploading instead of discovering a full library as a failed request.\n\n**The figures are per subscription, not per workspace.** The limit is the plan limit of the workspace's subscription owner (including the `stackable` multiplier and any purchased storage addons), and the usage is the total across every workspace that owner has. Two workspaces on the same subscription therefore report identical figures β€” the same numbers the web app's content library shows.\n\n**Usage is eventually consistent.** It is read from a cached aggregate that a scheduled sweep recomputes; deletes and uploads made through this API update it immediately, but media added by other means may take until the next sweep to appear.", "operationId": "getMediaStorage", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Storage figures retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Storage usage retrieved successfully." }, "data": { "properties": { "total_bytes": { "description": "The plan's media storage limit, in bytes, including addons", "type": "integer", "format": "int64", "example": 10737418240 }, "used_bytes": { "description": "Storage currently consumed, in bytes", "type": "integer", "format": "int64", "example": 3221225472 }, "available_bytes": { "description": "Remaining space in bytes; 0 when the subscription is over its limit", "type": "integer", "format": "int64", "example": 7516192768 }, "used_percentage": { "description": "used_bytes as a percentage of total_bytes, to one decimal place", "type": "number", "format": "float", "example": 30 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaValidationError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } }, "500": { "description": "Storage usage could not be read (MEDIA_STORAGE_UNAVAILABLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaServerError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/media/{media_id}/note": { "put": { "tags": [ "πŸ“ Content Library" ], "summary": "Set, update or clear a note on media", "description": "Writes a free-text note on a media item. Sending a note where one already exists replaces it; sending `null` or an empty string clears it. Notes are workspace-wide and last-writer-wins β€” any member (or API key) may change one, and `note_added_by` records the last editor rather than an owner. The note appears on the item in the web and mobile apps.", "operationId": "updateMediaNote", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "note": { "description": "The note text; null or an empty string clears an existing note", "type": "string", "maxLength": 500, "example": "Q4 campaign hero image β€” approved by legal", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Note written; the updated media item is returned", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Media note updated successfully." }, "data": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "note": { "type": "string", "example": "Q4 campaign hero image β€” approved by legal", "nullable": true }, "note_added_by": { "type": "string", "example": "610a1e660cb41530ca40d371", "nullable": true }, "is_brand_asset": { "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "404": { "description": "Media not found in this workspace (MEDIA_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaNotFound" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR) - note longer than 500 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaValidationError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/media/{media_id}/brand-asset": { "post": { "tags": [ "πŸ“ Content Library" ], "summary": "Flag media as a brand asset", "description": "Marks a media item as a brand asset so it feeds AI generation for the workspace's brand profile, exactly as flagging it from the Brand Knowledge tab does.\n\n**This moves the file and hides it from the default listing.** Flagging relocates the item into the workspace's `Brand Assets` folder, so the `folder_id` in the response will differ from the item's previous folder, and the item no longer appears in `GET /media` β€” brand assets are excluded from the general library. It is still returned by `GET /media?folder_id={brand_assets_folder_id}`, using the `folder_id` from this response. The previous folder is not recorded, so removing the flag later returns the item to Uncategorized rather than to where it came from.\n\n`profile_id` is optional: with it omitted the workspace's brand profile is used, and an empty one is created if the workspace has none yet. Supplying a `profile_id` that belongs to another workspace is rejected.", "operationId": "flagMediaAsBrandAsset", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "profile_id": { "description": "Brand profile to link to; defaults to the workspace's profile", "type": "string", "example": "64b2f1660cb41530ca40d399", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Media flagged; the updated item is returned, with folder_id now pointing at the Brand Assets folder", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Media flagged as a brand asset successfully." }, "data": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "is_brand_asset": { "type": "boolean", "example": true }, "folder_id": { "type": "string", "example": "64c3a2660cb41530ca40d4aa", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "404": { "description": "Media not found in this workspace (MEDIA_NOT_FOUND), or profile_id not found in this workspace (BRAND_PROFILE_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaNotFound" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaValidationError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“ Content Library" ], "summary": "Remove the brand asset flag from media", "description": "Clears the brand asset flag so the item no longer feeds AI generation. The media file itself is not deleted.\n\n**This moves the file.** Because the folder an item occupied before it was flagged is not recorded, removing the flag leaves it in Uncategorized (`folder_id: null`) rather than returning it to its original folder. Move it afterwards if it belongs somewhere specific.\n\nThe item reappears in `GET /media` once the flag is removed.\n\nThe call is idempotent: removing a flag that is not set succeeds and changes nothing.", "operationId": "unflagMediaAsBrandAsset", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "responses": { "200": { "description": "Flag removed; the updated item is returned, now in Uncategorized", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Brand asset flag removed successfully." }, "data": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "is_brand_asset": { "type": "boolean", "example": false }, "folder_id": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "404": { "description": "Media not found in this workspace (MEDIA_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaNotFound" } } } }, "422": { "description": "Validation error (VALIDATION_ERROR)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaValidationError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/media/folders": { "get": { "tags": [ "πŸ“ Content Library" ], "summary": "List media folders", "description": "Returns every media-library folder in the workspace. Folders the caller cannot access (shared/global folders without the access_shared_folder permission) are omitted. An empty library returns an empty array, not an error.", "operationId": "fetchMediaFolders", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Folders retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Media folders retrieved successfully." }, "folders": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "folder_name": { "type": "string", "example": "Campaign assets" }, "workspace_id": { "type": "string", "example": "610a1e660cb41530ca40d372" }, "root_folder_id": { "description": "Parent folder id, null for a top-level folder", "type": "string", "example": null, "nullable": true }, "is_root": { "type": "boolean", "example": true }, "is_global": { "description": "True for a folder shared across every workspace of the same owner", "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“ Content Library" ], "summary": "Create a media folder", "description": "Creates a folder in the workspace content library. Omit parent_folder_id to create a top-level folder, or supply it to create a subfolder. Folder names must be unique within their level.", "operationId": "createMediaFolder", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "folder_name" ], "properties": { "folder_name": { "type": "string", "maxLength": 40, "minLength": 3, "example": "Campaign assets" }, "parent_folder_id": { "description": "Create as a subfolder of this folder", "type": "string", "example": "625d06734ceb636c2f5e7743", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Folder created", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Folder created successfully." } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "404": { "description": "Parent folder not found in this workspace (FOLDER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaNotFound" } } } }, "422": { "description": "Validation error or duplicate folder name (VALIDATION_ERROR / FOLDER_CREATE_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaValidationError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/media/folders/{folder_id}": { "put": { "tags": [ "πŸ“ Content Library" ], "summary": "Rename a media folder", "description": "Renames a media-library folder. The Brand Assets system folder and shared/global folders cannot be renamed without the access_shared_folder permission.", "operationId": "updateMediaFolder", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "folder_name" ], "properties": { "folder_name": { "type": "string", "maxLength": 40, "minLength": 3, "example": "Q4 campaign assets" } }, "type": "object" } } } }, "responses": { "200": { "description": "Folder renamed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Folder updated successfully." } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "404": { "description": "Folder not found in this workspace (FOLDER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaNotFound" } } } }, "422": { "description": "Validation error or rename refused (VALIDATION_ERROR / FOLDER_UPDATE_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaValidationError" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“ Content Library" ], "summary": "Delete a media folder", "description": "**Irreversible and cascading.** Deleting a folder also permanently deletes every subfolder beneath it and every media file inside them, from both the library and cloud storage. If the folder is not empty the call returns 422 REQUIRES_DELETE_CONFIRMATION with the counts that would be destroyed and deletes nothing; resend with confirmed=true to proceed. Cloud storage removal is queued asynchronously, so the returned counts describe what was scheduled for deletion, not what has already been removed.", "operationId": "deleteMediaFolder", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "example": "625d06734ceb636c2f5e7743" } }, { "name": "confirmed", "in": "query", "description": "Set true to delete a folder that still contains media or subfolders", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Folder deleted", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Folder deleted successfully." }, "deleted_media_count": { "type": "integer", "example": 42 }, "deleted_subfolder_count": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - API key missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaForbidden" } } } }, "404": { "description": "Folder not found in this workspace (FOLDER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaNotFound" } } } }, "422": { "description": "Confirmation required (REQUIRES_DELETE_CONFIRMATION)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This folder contains 42 file(s) and 3 subfolder(s)..." }, "error_code": { "type": "string", "example": "REQUIRES_DELETE_CONFIRMATION" }, "context": { "properties": { "media_count": { "type": "integer", "example": 42 }, "subfolder_count": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/posts": { "get": { "tags": [ "πŸ“ Posts" ], "summary": "Fetch social media posts", "description": "Retrieve a paginated list of social media posts for a specific workspace with filtering options", "operationId": "fetchPosts", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "status[]", "in": "query", "description": "Filter by post status using array notation. Example: status[]=draft&status[]=scheduled&status[]=published. Use `notification_sent` / `notification_declined` for mobile push-notification publishing flow, and `processing` for posts currently being published.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "draft", "scheduled", "published", "failed", "rejected", "under_review", "missed_review", "partially_failed", "in_progress", "processing", "notification_sent", "notification_declined" ] }, "example": [ "scheduled", "published" ] } }, { "name": "date_from", "in": "query", "description": "Filter posts from this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "date_to", "in": "query", "description": "Filter posts to this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2026-12-31" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "default": 1, "minimum": 1, "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1, "example": 10 } }, { "name": "approval_assigned_to[]", "in": "query", "description": "Filter by approver user IDs. Returns posts where these users are assigned as approvers.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "example": "690d926bde7774c0dd0fc242" } } }, { "name": "approval_requested_by[]", "in": "query", "description": "Filter by users who requested approval. Returns posts submitted for review by these users.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "example": "690d926bde7774c0dd0fc242" } } }, { "name": "labels[]", "in": "query", "description": "Filter posts by label IDs.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } }, { "name": "campaigns[]", "in": "query", "description": "Filter posts by campaign (folder) IDs.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "example": "66a1f2e4c8b9a1234567890c" } } }, { "name": "content_category[]", "in": "query", "description": "Filter posts by content category IDs.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "example": "625d06734ceb636c2f5e7743" } } }, { "name": "created_by[]", "in": "query", "description": "Filter posts by the user IDs who created them.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "example": "690d926bde7774c0dd0fc242" } } }, { "name": "comment_status", "in": "query", "description": "Filter posts by comment resolution status. `all` (default) returns all posts regardless of comment state.", "schema": { "type": "string", "default": "all", "enum": [ "resolved", "unresolved", "all" ], "example": "unresolved" } } ], "responses": { "200": { "description": "Posts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Posts retrieved successfully" }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 25 }, "last_page": { "type": "integer", "example": 3 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 10 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PostObject" } } }, "type": "object" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "properties": { "status": { "type": "array", "items": { "type": "string", "example": "The selected status is invalid." } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to workspace" } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ“ Posts" ], "summary": "Create a new social media post", "description": "Create a new social media post with simplified payload structure", "operationId": "createPost", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "description": "Post creation payload", "required": true, "content": { "application/json": { "schema": { "required": [ "content", "accounts", "scheduling" ], "properties": { "content": { "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 5000, "example": "Check out our latest product launch! " }, "media": { "description": "Media content for the post. Every image and video is saved to the workspace media library during validation (URLs and media IDs already in the library are reused) and checked against each selected platform's limits: file size, dimensions, aspect ratio, duration and GIF support, for that platform's post type. Media that breaks a limit rejects the post with 400 and an error on the exact field (for example `content.media.images.2`), and anything the request saved is removed again. A video whose bitrate is above a platform's recommendation is accepted with a `warning`.", "properties": { "images": { "type": "array", "items": { "type": "string", "format": "url", "example": "https://example.com/image1.jpg" }, "maxItems": 10 }, "video": { "type": "string", "format": "url", "example": "https://example.com/video.mp4" }, "video_thumbnail": { "description": "Optional custom video thumbnail image URL, uploaded to the media library the same way as content images. Used by YouTube regular videos, Facebook videos and Reels, Instagram Reels, LinkedIn videos and Pinterest video Pins. Other platforms keep their automatic thumbnail. On update, leave it out to keep the current custom thumbnail, or send null to go back to the automatic one. Can also be set per platform in `platform_overrides..content.media.video_thumbnail`.", "type": "string", "format": "url", "example": "https://example.com/cover.jpg", "nullable": true }, "media_ids": { "description": "Array of content library IDs (from GET /media endpoint). Media already in the library will be used directly without re-uploading. Can be combined with images/video URLs.", "type": "array", "items": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "maxItems": 10 } }, "type": "object" } }, "type": "object" }, "platform_overrides": { "description": "Optional per-platform content overrides, keyed by platform name (facebook, instagram, twitter, linkedin, pinterest, youtube, tiktok, gmb, tumblr, threads, bluesky, telegram). `content.text` merges independently with the top-level `content.text` β€” an override with only `media`/`post_type` still keeps the common text. `content.media` (images + video together) is atomic: an override that includes a `media` key defines that platform's media ENTIRELY β€” whichever of `images`/`video` it doesn't set is empty/none for that platform, not inherited from the common `content.media`. An override with no `media` key at all inherits the common images/video wholesale. This matters because a platform can never publish mixed images+video (only Facebook/Instagram support it) β€” e.g. a TikTok override supplying only `video` gets no images at all, rather than inheriting the common images and becoming an invalid mixed post. `content.post_type` overrides the top-level `post_type` for that platform only (same allowed values); omitted, that platform falls back to the top-level `post_type`. Omit `platform_overrides` entirely to publish the same `content` to every platform.", "properties": { "facebook": { "properties": { "content": { "properties": { "text": { "type": "string", "maxLength": 5000, "example": "Facebook-specific caption πŸ“˜" }, "post_type": { "description": "Overrides the top-level post_type for Facebook only.", "type": "string", "enum": [ "feed", "feed+reel", "reel", "carousel", "story", "feed+story", "feed+reel+story", "reel+story", "carousel+story", "video", "shorts", "poll" ], "example": "story" }, "media": { "properties": { "images": { "type": "array", "items": { "type": "string", "format": "url", "example": "https://example.com/fb-image.jpg" }, "maxItems": 10 }, "video": { "type": "string", "format": "url", "example": "https://example.com/fb-video.mp4" }, "media_ids": { "description": "Content library IDs for this platform, the same as `content.media.media_ids`. Images join this override's `images`, a video becomes its `video`. Works for every platform key in `platform_overrides`.", "type": "array", "items": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "maxItems": 10 } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "instagram": { "properties": { "content": { "properties": { "text": { "type": "string", "maxLength": 5000, "example": "IG-only caption πŸ“Έ" }, "post_type": { "description": "Overrides the top-level post_type for Instagram only.", "type": "string", "enum": [ "feed", "feed+reel", "reel", "carousel", "story", "feed+story", "feed+reel+story", "reel+story", "carousel+story", "video", "shorts", "poll" ], "example": "reel" }, "media": { "properties": { "images": { "type": "array", "items": { "type": "string", "format": "url", "example": "https://example.com/ig-image.jpg" }, "maxItems": 10 }, "video": { "type": "string", "format": "url", "example": "https://example.com/ig-video.mp4" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "tiktok": { "properties": { "content": { "properties": { "text": { "type": "string", "maxLength": 5000, "example": "TikTok-specific caption 🎡" }, "post_type": { "description": "Overrides the top-level post_type for TikTok only.", "type": "string", "enum": [ "video", "carousel" ], "example": "carousel" }, "media": { "properties": { "images": { "type": "array", "items": { "type": "string", "format": "url", "example": "https://example.com/tt-image.jpg" }, "maxItems": 10 }, "video": { "type": "string", "format": "url", "example": "https://example.com/tt-video.mp4" } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "accounts": { "description": "Array of account IDs to post to (platform will be automatically detected). Optional if content_category_id is provided.", "type": "array", "items": { "type": "string", "example": "BjniecijWv" }, "example": [ "BjniecijWv", "350830594784444", "17841453340834745" ] }, "content_category_id": { "description": "Optional content category ID. When provided, accounts from the category will be used. Can be combined with accounts array for merged unique accounts.", "type": "string", "example": "625d06734ceb636c2f5e7743" }, "post_type": { "description": "Optional post type. See docs for platform-specific supported values. Defaults to 'feed' when omitted. For Facebook carousel posts you may set post_type='carousel', but you MUST also provide facebook_options.carousel.is_carousel_post=true with at least 2 cards β€” otherwise it is rejected with 400. For a LinkedIn poll set post_type='poll' and provide linkedin_options.poll (text-only); the poll is ignored for any other post_type.", "type": "string", "enum": [ "feed", "feed+reel", "reel", "carousel", "story", "feed+story", "feed+reel+story", "reel+story", "carousel+story", "video", "shorts", "poll" ], "example": "reel+story" }, "post_video_title": { "description": "Optional video title for platforms that support it (YouTube, LinkedIn). Will be set in common_sharing_details video title, YouTube options, and LinkedIn options.", "type": "string", "example": "My Amazing Video Title" }, "hide_client": { "description": "Optional. When true, hides draft posts from client users. Ignored and stored as false for non-draft posts.", "type": "boolean", "example": true }, "scheduling": { "required": [ "publish_type" ], "properties": { "publish_type": { "type": "string", "enum": [ "scheduled", "draft", "queued", "content_category" ], "example": "scheduled" }, "scheduled_at": { "type": "string", "format": "date-time", "example": "2026-01-10 15:30:00" }, "repeat": { "description": "Publish this post again on a fixed interval by creating independent children. Only for publish_type `now` or `scheduled`. `enabled` is the switch and nothing happens without it β€” the read side returns this block WITHOUT `enabled`, so echoing a post back cannot create children by accident. Never inherited: an update without `enabled: true` creates no children even on a post that already repeats, and an update with it adds a further batch β€” the same as toggling repeat back on in the composer. Children drop Twitter (duplicate content is not allowed there), so a post targeting only Twitter is rejected. Children are independent posts and each carries the post's approvers, so N children means N approval items.", "required": [ "enabled" ], "properties": { "enabled": { "description": "Set true to create children. When false or omitted the other fields are ignored.", "type": "boolean", "example": true }, "type": { "description": "Required when enabled is true.", "type": "string", "enum": [ "Day", "Week", "Month" ], "example": "Day" }, "times": { "description": "How many children to create, in addition to this post.", "type": "integer", "maximum": 30, "minimum": 1, "example": 2 }, "gap": { "description": "Interval between children, in units of `type`. A `Day` interval must be at least 3.", "type": "integer", "maximum": 99, "minimum": 1, "example": 3 } }, "type": "object" } }, "type": "object" }, "first_comment": { "description": "Optional first comment for the post", "required": [ "message", "accounts" ], "properties": { "message": { "type": "string", "maxLength": 2000, "example": "Great product! Check the details in comments." }, "accounts": { "description": "Account IDs for first comment (must be subset of main accounts)", "type": "array", "items": { "type": "string", "example": "BjniecijWv" }, "example": [ "BjniecijWv", "350830594784444" ] } }, "type": "object" }, "gmb_options": { "description": "Optional Google Business Profile specific options", "properties": { "topic_type": { "type": "string", "enum": [ "STANDARD", "EVENT", "OFFER" ], "example": "EVENT" }, "start_date": { "type": "string", "format": "date", "example": "2026-01-10" }, "end_date": { "type": "string", "format": "date", "example": "2026-01-11" }, "title": { "type": "string", "maxLength": 100, "example": "Special Event" }, "action_type": { "type": "string", "enum": [ "BOOK", "ORDER", "LEARN_MORE" ], "example": "BOOK" }, "cta_link": { "type": "string", "format": "uri", "example": "https://example.com/book" } }, "type": "object" }, "youtube_options": { "description": "Optional YouTube specific options", "properties": { "title": { "type": "string", "maxLength": 100, "example": "My Video Title" }, "privacy_status": { "type": "string", "enum": [ "public", "private" ], "example": "public" }, "category": { "type": "string", "enum": [ "CARS_VEHICLES", "COMEDY", "EDUCATION", "ENTERTAINMENT", "FILM_ANIMATION", "GAMING", "HOW_TO_STYLE", "MUSIC", "NEWS_POLITICS", "NON_PROFITS_ACTIVISM", "PEOPLE_BLOGS", "PETS_ANIMALS", "SCIENCE_TECHNOLOGY", "SPORT", "TRAVEL_EVENTS" ], "example": "COMEDY" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 30 }, "example": [ "tutorial", "demo" ] }, "license": { "type": "string", "enum": [ "youtube", "creativeCommon" ], "example": "youtube" }, "made_for_kids": { "type": "boolean", "example": false } }, "type": "object" }, "tiktok_options": { "description": "Optional TikTok specific options", "properties": { "privacy_level": { "type": "string", "enum": [ "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY" ], "example": "PUBLIC_TO_EVERYONE" }, "disable_comment": { "type": "boolean", "example": false }, "disable_duet": { "type": "boolean", "example": false }, "disable_stitch": { "type": "boolean", "example": false }, "auto_add_music": { "type": "boolean", "example": false }, "brand_content_toggle": { "type": "boolean", "example": false }, "brand_organic_toggle": { "type": "boolean", "example": false }, "disclose_commercial_content": { "type": "boolean", "example": false }, "is_aigc": { "type": "boolean", "example": false }, "video_cover_timestamp_ms": { "description": "TikTok cover frame, in milliseconds from the start of the video. TikTok does not accept a custom image. Defaults to 0 when left out; on update, a kept custom thumbnail keeps its current frame.", "type": "integer", "default": 0, "minimum": 0, "example": 0, "nullable": true } }, "type": "object" }, "twitter_options": { "description": "Optional Twitter/X thread options", "properties": { "has_threaded_tweets": { "type": "boolean", "example": true }, "threaded_tweets": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Part 1 of the thread" }, "media": { "description": "Media URLs or content library IDs. Twitter/X allows multiple images or one video only.", "type": "array", "items": { "type": "string", "example": "https://example.com/media.jpg" }, "maxItems": 10 } }, "type": "object" }, "maxItems": 10 } }, "type": "object" }, "threads_options": { "description": "Optional Threads multi-post options", "properties": { "has_multi_threads": { "type": "boolean", "example": true }, "multi_threads": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Part 1 of the thread" }, "media": { "description": "Media URLs or content library IDs. Threads allows mixed images and videos in the same item.", "type": "array", "items": { "type": "string", "example": "https://example.com/media.jpg" }, "maxItems": 10 } }, "type": "object" }, "maxItems": 10 } }, "type": "object" }, "pinterest_options": { "description": "Optional Pinterest specific options (saved to sharing details)", "properties": { "title": { "type": "string", "maxLength": 100, "example": "My Pin Title" }, "link": { "type": "string", "format": "uri", "example": "https://example.com/article" } }, "type": "object" }, "facebook_options": { "description": "Optional Facebook specific options.", "properties": { "facebook_background_id": { "description": "Facebook text-format preset ID for colored-background text posts. Only applies to plain text posts β€” the request is rejected if media (images, video, or media_ids) is also provided. Use GET /api/v1/facebook/text-backgrounds to list valid preset IDs.", "type": "string", "example": "106018623298955", "nullable": true }, "collaborators": { "description": "Facebook Reel collaborators to invite. Each item is a Facebook Page identifier β€” a numeric Page ID (recommended), an @username, or a Page URL (resolved to a Page ID at publish time). Applies only to Reels published to Facebook Pages; personal profiles are not valid collaborators. Facebook allows up to 10 invites per Page per 24 hours.", "type": "array", "items": { "type": "string", "example": "1184502918080941" }, "maxItems": 10 }, "carousel": { "description": "Optional Facebook carousel post. When enabled, the post is published as a multi-card carousel on the selected Facebook Pages instead of a regular feed post. Carousel is image-only β€” video is not allowed. If `content.media.images` is empty, card images are auto-mirrored so non-Facebook accounts in the same post still receive images.", "properties": { "is_carousel_post": { "description": "Set true to publish as carousel.", "type": "boolean", "example": true }, "cards": { "description": "Between 2 and 10 carousel cards. Required when is_carousel_post is true.", "type": "array", "items": { "required": [ "link" ], "properties": { "image": { "description": "Card image URL. External URLs are uploaded to the content library; library URLs are used as-is. Required unless `media_id` is sent.", "type": "string", "format": "uri", "example": "https://example.com/card1.jpg" }, "media_id": { "description": "Content library ID of an image to use as the card image, instead of `image`. Send one or the other.", "type": "string", "example": "625d06734ceb636c2f5e7743" }, "title": { "type": "string", "maxLength": 255, "example": "Card 1 Title" }, "description": { "type": "string", "maxLength": 1000, "example": "Short description shown under the title." }, "link": { "description": "Destination URL when the card is tapped.", "type": "string", "format": "uri", "example": "https://example.com/landing/1" } }, "type": "object" }, "maxItems": 10, "minItems": 2 }, "accounts": { "description": "Optional subset of `accounts[]` to publish as carousel, using the same ids as `accounts[]` (the `id` from GET /accounts, i.e. the platform identifier). Only Facebook accounts in this subset will use carousel mode; other Facebook accounts in `accounts[]` will publish normally. Omit to apply carousel to ALL Facebook accounts in the post.", "type": "array", "items": { "type": "string", "example": "1329910333529595" } }, "call_to_action": { "description": "CTA button shown on every card. Maps to Facebook Graph `child_attachments.call_to_action.type`.", "type": "string", "default": "NO_BUTTON", "enum": [ "NO_BUTTON", "ADD_TO_CART", "APPLY_NOW", "BET_NOW", "BOOK_TRAVEL", "BUY_NOW", "BUY_TICKETS", "CALL_NOW", "CONTACT_US", "DOWNLOAD", "GET_DIRECTIONS", "GET_OFFER", "GET_QUOTE", "GO_LIVE", "INSTALL_MOBILE_APP", "LEARN_MORE", "LIKE_PAGE", "LISTEN_MUSIC", "OPEN_LINK", "ORDER_NOW", "PLAY_GAME", "REGISTER_NOW", "REQUEST_TIME", "SAVE", "MESSAGE_PAGE", "WHATSAPP_MESSAGE", "SHOP_NOW", "SIGN_UP", "SUBSCRIBE", "USE_APP", "WATCH_MORE", "WATCH_VIDEO" ], "example": "SHOP_NOW" }, "end_card": { "description": "Include a Facebook end card after the last card.", "type": "boolean", "default": false, "example": true }, "end_card_url": { "description": "Destination URL for the end card. Falls back to the first card's link when omitted.", "type": "string", "format": "uri", "example": "https://example.com", "nullable": true } }, "type": "object" } }, "type": "object" }, "instagram_options": { "description": "Optional Instagram specific options.", "properties": { "collaborators": { "description": "Instagram collaborators (co-authors) to invite by username. Up to 3. Only public Instagram profiles connected via Facebook can be added; not applicable to Story posts. Cannot be combined with trial_reel.", "type": "array", "items": { "type": "string", "example": "@nike" }, "maxItems": 3 }, "trial_reel": { "description": "Publish as a trial reel β€” shown to non-followers first, so it does not appear on the profile grid or in follower feeds. Requires post_type=reel exactly (not feed+reel, which shares to the feed) and a video. Collaborators and share-to-story are not supported alongside it and are dropped. Only available to public professional Instagram accounts that meet Instagram's own trial reel requirements; publishing fails for accounts that do not, and the Instagram error is reported per account. Not available when the workspace publishes Instagram via the mobile app.", "properties": { "enabled": { "description": "Publish this reel as a trial reel.", "type": "boolean", "default": false, "example": true }, "graduation_strategy": { "description": "How the trial reel is shared with followers. SS_PERFORMANCE lets Instagram graduate it automatically if it performs well; MANUAL requires graduating it by hand in the Instagram app β€” there is no API for graduating a trial reel.", "type": "string", "default": "SS_PERFORMANCE", "enum": [ "MANUAL", "SS_PERFORMANCE" ], "example": "SS_PERFORMANCE" } }, "type": "object" } }, "type": "object" }, "linkedin_options": { "description": "Optional LinkedIn specific options. A LinkedIn carousel is created automatically when 2+ images are attached (rendered as a PDF document) and applies to every LinkedIn account in accounts[] β€” no extra flags needed; use title to name that document. Provide poll to publish a text-only poll instead.", "properties": { "title": { "description": "Title for the LinkedIn document/carousel post (shown on the generated PDF).", "type": "string", "maxLength": 255, "example": "Q3 Product Highlights", "nullable": true }, "accounts": { "description": "Optional subset of accounts[] the carousel targets, using the same ids as accounts[] (the `id` from GET /accounts, i.e. the platform identifier). Only LinkedIn accounts in this subset publish as a carousel; omit to apply the carousel to ALL LinkedIn accounts in the post. Must be LinkedIn accounts present in accounts[]. Ignored for non-carousel posts.", "type": "array", "items": { "type": "string", "example": "105256406" } }, "poll": { "description": "LinkedIn poll. Only used when post_type='poll' (ignored otherwise). Poll posts are text-only β€” the request is rejected if images or a video are also provided. Applies to every LinkedIn account in accounts[].", "required": [ "question", "options" ], "properties": { "question": { "type": "string", "maxLength": 140, "example": "Which framework do you prefer?" }, "options": { "description": "Between 2 and 4 poll options, each up to 30 characters.", "type": "array", "items": { "type": "string", "maxLength": 30, "example": "Vue" }, "maxItems": 4, "minItems": 2 }, "duration": { "type": "string", "default": "ONE_DAY", "enum": [ "ONE_DAY", "THREE_DAYS", "SEVEN_DAYS", "FOURTEEN_DAYS" ], "example": "SEVEN_DAYS" } }, "type": "object" } }, "type": "object" }, "labels": { "description": "Optional array of label IDs to attach to the post. Maximum 20 labels. Must be valid label IDs for the workspace.", "type": "array", "items": { "type": "string", "example": "625d06734ceb636c2f5e7743" }, "maxItems": 20 }, "campaign_id": { "description": "Optional campaign (folder) ID to assign the post to. Must be a valid campaign ID for the workspace.", "type": "string", "example": "625d06734ceb636c2f5e7743", "nullable": true }, "approval": { "description": "Optional legacy single-level approval. Sends the post for review by the listed approvers. Mutually exclusive with approval_workflow.", "properties": { "approvers": { "description": "User IDs who can approve the post. Must be workspace team members and cannot include the post creator.", "type": "array", "items": { "type": "string", "example": "627a078300a7d866600e7d02" } }, "approve_option": { "description": "Whether any single approver or all approvers must approve", "type": "string", "enum": [ "anyone", "everyone" ], "example": "anyone" }, "notes": { "description": "Optional notes for approvers", "type": "string", "maxLength": 1000, "example": "Please review before publishing", "nullable": true } }, "type": "object" }, "approval_workflow": { "description": "Optional multi-level approval workflow. Mutually exclusive with approval. On create, provide workflow_id to attach a workflow (from GET .../approval-workflows) β€” a failed attach is surfaced as a non-fatal `warning`, not a request error.", "properties": { "workflow_id": { "description": "ID of the workflow to attach (from GET .../approval-workflows).", "type": "string", "example": "66a1f2e4c8b9a1234567890d" }, "notes": { "description": "Optional notes stored with the workflow submission", "type": "string", "maxLength": 1000, "example": "Please review before publishing", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Post created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Post created successfully. Use the returned `id` as `post_id` to update, delete, approve, or comment on this post." }, "data": { "properties": { "id": { "type": "string", "example": "66a1f2e4c8b9a1234567890a" }, "post_url": { "type": "string", "example": "https://example.com" }, "warning": { "description": "Present when the post was created but something needs attention: approval_workflow.workflow_id was provided and the workflow attach failed (retry it via Update Post), or a video's bitrate is above what a platform recommends, so the platform may re-encode or reject it.", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation failed. Includes media that cannot be downloaded, is not the expected type, does not fit the storage left, or breaks a selected platform's limits.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "properties": { "content.text": { "type": "array", "items": { "type": "string", "example": "The content.text field is required." } }, "content.media.images.0": { "type": "array", "items": { "type": "string", "example": "X (Twitter) allows images up to 5 MB. This image is 6 MB." } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to workspace" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to create post: Internal error occurred" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/posts/{post_id}": { "get": { "tags": [ "πŸ“ Posts" ], "summary": "Get a single post", "description": "Retrieve a single social media post by its ID for a specific workspace", "operationId": "getPost", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "post_id", "in": "path", "description": "Post ID", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890a" } } ], "responses": { "200": { "description": "Post retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Post retrieved successfully." }, "data": { "$ref": "#/components/schemas/PostObject" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied." } }, "type": "object" } } } }, "404": { "description": "Post not found in this workspace, or not visible to the caller", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Post not found" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "πŸ“ Posts" ], "summary": "Update an existing social media post", "description": "Update a post that has NOT been published yet. Accepts the same payload as Create Post (full replace of the post's content, accounts, scheduling and platform options). Posts that are already published, or currently being published, cannot be edited. See the Create Post endpoint for the full request body schema.", "operationId": "updatePost", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "post_id", "in": "path", "description": "ID of the post to update", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890a" } } ], "requestBody": { "description": "Same payload as Create Post (full replace). The three required top-level fields are shown here; all optional fields (post_type, first_comment, platform options, labels, campaign_id, approval, etc.) are identical to Create Post.", "required": true, "content": { "application/json": { "schema": { "required": [ "content", "accounts", "scheduling" ], "properties": { "content": { "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 5000, "example": "Updated post text" } }, "type": "object" }, "accounts": { "type": "array", "items": { "type": "string", "example": "BjniecijWv" } }, "post_video_title": { "description": "Video title. Left out, the post keeps its current video title (including one set in the composer); sent, it replaces it.", "type": "string", "example": "My Amazing Video Title" }, "scheduling": { "required": [ "publish_type" ], "properties": { "publish_type": { "type": "string", "enum": [ "scheduled", "draft", "queued", "content_category" ], "example": "scheduled" }, "scheduled_at": { "type": "string", "format": "date-time", "example": "2026-01-10 15:30:00" }, "repeat": { "description": "Publish this post again on a fixed interval by creating independent children. Only for publish_type `now` or `scheduled`. `enabled` is the switch and nothing happens without it β€” the read side returns this block WITHOUT `enabled`, so echoing a post back cannot create children by accident. Never inherited: an update without `enabled: true` creates no children even on a post that already repeats, and an update with it adds a further batch β€” the same as toggling repeat back on in the composer. Children drop Twitter (duplicate content is not allowed there), so a post targeting only Twitter is rejected. Children are independent posts and each carries the post's approvers, so N children means N approval items.", "required": [ "enabled" ], "properties": { "enabled": { "description": "Set true to create children. When false or omitted the other fields are ignored.", "type": "boolean", "example": true }, "type": { "description": "Required when enabled is true.", "type": "string", "enum": [ "Day", "Week", "Month" ], "example": "Day" }, "times": { "description": "How many children to create, in addition to this post.", "type": "integer", "maximum": 30, "minimum": 1, "example": 2 }, "gap": { "description": "Interval between children, in units of `type`. A `Day` interval must be at least 3.", "type": "integer", "maximum": 99, "minimum": 1, "example": 3 } }, "type": "object" } }, "type": "object" }, "approval": { "description": "Optional legacy single-level approval (mutually exclusive with approval_workflow). Rejected with 422 if this post already has an active/rejected workflow β€” remove it first via approval_workflow.workflow_action=remove.", "properties": { "approvers": { "type": "array", "items": { "type": "string", "example": "627a078300a7d866600e7d02" } }, "approve_option": { "type": "string", "enum": [ "anyone", "everyone" ], "example": "anyone" }, "notes": { "type": "string", "maxLength": 1000, "example": "Please review before publishing", "nullable": true } }, "type": "object" }, "approval_workflow": { "description": "Optional multi-level workflow (mutually exclusive with approval). Provide exactly ONE of workflow_id (attach/override a workflow) or workflow_action (act on this post's EXISTING active/rejected workflow).", "properties": { "workflow_id": { "description": "Attach a new workflow, or override the post's existing one. A failed attach is surfaced as a non-fatal `warning`.", "type": "string", "example": "66a1f2e4c8b9a1234567890d" }, "workflow_action": { "description": "Act on the EXISTING workflow. Allowed values depend on its current status: rejected workflows accept restart/resume/remove; pending or partially-approved workflows accept restart/renotify_current/keep/remove. 422 if this post has no active workflow, or if the action isn't valid for its current status.", "type": "string", "enum": [ "restart", "resume", "renotify_current", "keep", "remove" ], "example": "keep" }, "notes": { "type": "string", "maxLength": 1000, "example": "Please review before publishing", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Post updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Post updated successfully. Use the returned `id` as `post_id` for further updates, deletion, approval, or comments." }, "data": { "properties": { "id": { "type": "string", "example": "66a1f2e4c8b9a1234567890a" }, "post_url": { "type": "string", "example": "https://app.contentstudio.io/my-workspace/publisher/planner/list-view?plan_ids=66a1f2e4c8b9a1234567890a", "nullable": true }, "warning": { "description": "Present when the post was updated but something needs attention: approval_workflow.workflow_id was provided and the workflow attach failed, or a video's bitrate is above what a platform recommends.", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Insufficient permissions" } }, "type": "object" } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Post not found" } }, "type": "object" } } } }, "422": { "description": "Post cannot be edited (already published or currently publishing)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Post cannot be edited (already published or currently publishing)" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ“ Posts" ], "summary": "Delete a social media post", "description": "Delete a specific social media post by ID. Optionally delete from social platforms by setting delete_from_social to true.", "operationId": "deletePost", "parameters": [ { "name": "workspace_id", "in": "path", "description": "The workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "post_id", "in": "path", "description": "The post ID to delete", "required": true, "schema": { "type": "string", "example": "68872722d9c2a0366a00ae32" } } ], "requestBody": { "description": "Optional parameters for social platform deletion", "required": false, "content": { "application/json": { "schema": { "properties": { "delete_from_social": { "description": "When true, attempts to delete from social platforms before removing from ContentStudio", "type": "boolean", "example": true }, "account_ids": { "description": "Platform account IDs to target. Omit to target all published accounts.", "type": "array", "items": { "type": "string", "example": "350830594784444" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Post deleted successfully (all accounts succeeded or no social deletion requested)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Post deleted successfully" } }, "type": "object" } } } }, "207": { "description": "Multi-status - mixed outcomes across accounts", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "post_id": { "type": "string", "example": "68872722d9c2a0366a00ae32" }, "contentstudio": { "type": "string", "example": "deleted" }, "accounts": { "type": "object", "additionalProperties": { "properties": { "platform": { "type": "string", "example": "facebook" }, "name": { "type": "string", "example": "My Business Page" }, "status": { "type": "string", "enum": [ "deleted", "error", "not_supported", "skipped", "not_published" ], "example": "deleted" }, "reason": { "type": "string", "example": "Access token expired." }, "post_url": { "type": "string", "example": "https://www.instagram.com/p/ABC123/" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Insufficient permissions" } }, "type": "object" } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Post not found" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/posts/{post_id}/approval": { "post": { "tags": [ "πŸ“ Posts" ], "summary": "Approve or reject a post", "description": "Approve or reject a single post that is under review with an optional comment.", "operationId": "approvalAction", "parameters": [ { "name": "workspace_id", "in": "path", "description": "The workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "post_id", "in": "path", "description": "The post ID to approve or reject", "required": true, "schema": { "type": "string", "example": "68872722d9c2a0366a00ae32" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "action" ], "properties": { "action": { "description": "Action to perform", "type": "string", "enum": [ "approve", "reject" ] }, "comment": { "description": "Optional comment for the approval/rejection", "type": "string", "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Approval action completed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Post approved successfully" } }, "type": "object" } } } }, "400": { "description": "Bad request or action failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Forbidden - User is not an approver. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string" } }, "type": "object" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/scheduling/optimal-times": { "post": { "tags": [ "πŸ•’ Scheduling" ], "summary": "Get optimal posting times", "description": "Analyse historical performance of the workspace's connected accounts and return the best times to publish, both pooled across accounts (`global`) and per account (`individual`). **A slot is one recommended posting time β€” a weekday and an hour, in the workspace timezone.** Each account is scored across the week and slots come back ranked best-first, so `slots: 3` means *the three best hours to post*. The slot fields only control how much of that ranking is returned: they never change the analysis, and they do not affect `heatmap_matrix`, which always carries every hour that had signal. Omit `entities` to analyse every account connected to the workspace. Times are always expressed in the workspace timezone (echoed under `meta.timezone`); there is no timezone parameter.", "operationId": "schedulingOptimalTimes", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "entities": { "description": "Accounts to analyse. Omit for every connected account. Each `id` must be an account `_id` from GET /accounts.", "type": "array", "items": { "required": [ "id", "type" ], "properties": { "id": { "type": "string", "example": "350830594784444" }, "type": { "type": "string", "enum": [ "facebook", "instagram", "linkedin", "twitter", "tiktok", "youtube", "pinterest", "threads", "gmb", "tumblr", "bluesky", "telegram" ] }, "slots": { "description": "How many recommended times to return for this account, best-first. Overrides `per_account_slots`.", "type": "integer", "maximum": 24, "minimum": 1 } }, "type": "object" } }, "global_slots": { "description": "How many recommended times to return in the pooled `global` view, best-first.", "type": "integer", "default": 5, "maximum": 24, "minimum": 1 }, "per_account_slots": { "description": "How many recommended times to return for each account that does not set its own `slots`.", "type": "integer", "default": 3, "maximum": 24, "minimum": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Recommendations generated. A workspace with too little history still returns 200 β€” the accounts are listed under meta.missing_entities.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "meta": { "properties": { "generated_at": { "type": "string", "format": "date-time" }, "timezone": { "description": "The workspace timezone the slots are expressed in", "type": "string", "example": "America/New_York" }, "warnings": { "type": "array", "items": { "type": "string" } }, "missing_entities": { "type": "array", "items": { "type": "string" } }, "ai_fallback_entities": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "global": { "description": "Pooled view across all analysed accounts. Null when no account had usable data.", "properties": { "top_recommendations": { "type": "array", "items": { "properties": { "rank": { "type": "integer", "example": 1 }, "day": { "type": "string", "example": "Wednesday" }, "date": { "type": "string", "example": "2026-08-12" }, "time": { "type": "string", "example": "14" }, "score": { "type": "integer", "example": 100 }, "platform_breakdown": { "type": "object", "example": { "facebook": 60, "instagram": 40 } } }, "type": "object" } }, "heatmap_matrix": { "description": "Sparse [hour, day_index, score] triples; day_index 0 = Monday.", "properties": { "data": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } } } }, "type": "object" }, "dates_key": { "type": "array", "items": { "type": "string", "format": "date" } } }, "type": "object", "nullable": true }, "individual": { "description": "Per-account breakdown keyed by account id.", "type": "object", "example": { "350830594784444": { "platform": "facebook", "source": "data_driven", "top_recommendations": [], "heatmap_matrix": { "data": [] }, "dates_key": [] } } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Not a member of this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`." }, "422": { "description": "Validation error, unknown entities, or no connected accounts" }, "429": { "description": "Too many requests" }, "502": { "description": "Post time optimizer unavailable" } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/share-links": { "get": { "tags": [ "πŸ”— Share Links" ], "summary": "List shareable links", "description": "Retrieve the workspace's planner share links, newest first. Neither the link password nor its external-approval tokens are ever returned.", "operationId": "fetchShareLinks", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "per_page", "in": "query", "description": "Max 100.", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "example": 10 } }, { "name": "search", "in": "query", "description": "Case-insensitive match on the link name.", "required": false, "schema": { "type": "string", "example": "recap" } } ], "responses": { "200": { "description": "Share links retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkList" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkForbidden" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ”— Share Links" ], "summary": "Create a shareable link", "description": "Create a public link to a set of posts or a calendar window. `scope` defaults to `selection` (an explicit post list), which needs at least one `plans` or `notes` id. `future` and `all` share a calendar window instead: they require `view: calendar` plus a `calendar_date` range, and only that pairing takes no post ids β€” the window is resolved on every fetch, so any `plans`/`notes` sent with it are stored but never read. Approval invitations are not part of create β€” use the send-invitations endpoint afterwards.", "operationId": "createShareLink", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Letters, digits and spaces only β€” it is slugified into the public URL.", "type": "string", "maxLength": 255, "minLength": 3, "example": "Q1 Client Recap" }, "scope": { "description": "`selection` shares the listed posts. `future`/`all` share a calendar window and require `view: calendar`.", "type": "string", "default": "selection", "enum": [ "selection", "future", "all" ], "example": "selection" }, "view": { "description": "Presentation hint for the viewer.", "type": "string", "default": "list", "enum": [ "list", "calendar", "compact_list" ], "example": "list" }, "calendar_date": { "description": "Range anchor, required for `future`/`all` and rejected otherwise.", "type": "string", "example": "2026-01-01 - 2026-03-31" }, "plans": { "description": "Post IDs, each in this workspace. Required unless `notes` is given, except on a `future`/`all` calendar window, where the ids are ignored.", "type": "array", "items": { "type": "string", "example": "66a1f2e4c8b9a1234567890c" }, "maxItems": 500 }, "notes": { "description": "Note IDs, each in this workspace. Stands in for `plans`; ignored on a `future`/`all` calendar window.", "type": "array", "items": { "type": "string" }, "maxItems": 500 }, "show_notes": { "type": "boolean", "example": false }, "is_password_protected": { "type": "boolean", "example": false }, "password": { "description": "Write-only β€” never returned.", "type": "string", "minLength": 4, "example": "hunter2" }, "is_single_post": { "description": "When true, `plans` must hold exactly one id and `scope` must be `selection`.", "type": "boolean", "example": false }, "allow_external_comments": { "type": "boolean", "example": false }, "allow_external_approval_actions": { "description": "Must be false when `scope` is `future`/`all`.", "type": "boolean", "example": false }, "social_selections": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Share link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkCreated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkForbidden" } } } }, "422": { "description": "Validation failed (`VALIDATION_ERROR`) or the create failed (`SHARE_LINK_CREATE_FAILED`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ShareLinkValidationError" }, { "$ref": "#/components/schemas/ShareLinkWriteFailed" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/share-links/{link_id}": { "get": { "tags": [ "πŸ”— Share Links" ], "summary": "Get a single shareable link", "description": "Retrieve one share link. Neither the link password nor its external-approval tokens are ever returned; `outstanding_invitations_count` is the safe projection of the token map.", "operationId": "fetchShareLink", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "link_id", "in": "path", "description": "The share link record id (the `id` field on the resource) β€” not the public `link_id` slug from the share URL.", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } ], "responses": { "200": { "description": "Share link retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkFetched" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkForbidden" } } } }, "404": { "description": "Share link not found in this workspace (`SHARE_LINK_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkNotFound" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "πŸ”— Share Links" ], "summary": "Update a shareable link", "description": "Partially update a link β€” anything omitted keeps its value. Also the enable/disable mechanism (`is_disabled`). Turning off password protection clears the stored password, and turning off `approval_flow` revokes every outstanding invitation token. `plans` cannot be changed after creation.", "operationId": "updateShareLink", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "link_id", "in": "path", "description": "The share link record id (the `id` field on the resource) β€” not the public `link_id` slug from the share URL.", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 3, "example": "Q1 Client Recap Final" }, "is_disabled": { "description": "Disable the link without deleting it.", "type": "boolean", "example": true }, "scope": { "description": "Switching to `selection` is refused when the link holds no post or note ids, since they cannot be added after create.", "type": "string", "enum": [ "selection", "future", "all" ] }, "view": { "type": "string", "enum": [ "list", "calendar", "compact_list" ] }, "calendar_date": { "type": "string", "example": "2026-01-01 - 2026-03-31" }, "notes": { "type": "array", "items": { "type": "string" } }, "show_notes": { "type": "boolean" }, "is_password_protected": { "description": "Setting this false clears the stored password.", "type": "boolean" }, "password": { "description": "Required when enabling protection. Write-only.", "type": "string", "minLength": 4 }, "allow_external_comments": { "type": "boolean" }, "allow_external_approval_actions": { "type": "boolean" }, "approval_flow": { "description": "Setting this false revokes all outstanding invitation tokens.", "type": "boolean" }, "approval_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 10 }, "approval_option": { "type": "string", "enum": [ "anyone", "everyone" ] }, "social_selections": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Share link updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkUpdated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkForbidden" } } } }, "404": { "description": "Share link not found in this workspace (`SHARE_LINK_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkNotFound" } } } }, "422": { "description": "Validation failed (`VALIDATION_ERROR`) or the update failed (`SHARE_LINK_UPDATE_FAILED`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ShareLinkValidationError" }, { "$ref": "#/components/schemas/ShareLinkWriteFailed" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ”— Share Links" ], "summary": "Delete a shareable link", "description": "Permanently delete a link; the public URL stops resolving immediately. There is no force flag, but the response reports how many external approvers still had un-actioned invitations, so a scripted cleanup can see that it cut them off mid-review.", "operationId": "deleteShareLink", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "link_id", "in": "path", "description": "The share link record id (the `id` field on the resource) β€” not the public `link_id` slug from the share URL.", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } ], "responses": { "200": { "description": "Share link deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkDeleted" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkForbidden" } } } }, "404": { "description": "Share link not found in this workspace (`SHARE_LINK_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkNotFound" } } } }, "422": { "description": "The delete failed (`SHARE_LINK_DELETE_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkWriteFailed" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/share-links/{link_id}/activity": { "get": { "tags": [ "πŸ”— Share Links" ], "summary": "Read what a client did through a share link", "description": "Every comment and every approve/reject a recipient left through THIS link, newest first. Both are stored on the posts themselves (`external_comments` and `external_actions`) and are filtered to this link's id, so activity a client left through a different link on the same post is not returned here.", "operationId": "fetchShareLinkActivity", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "link_id", "in": "path", "description": "The share link record id (the `id` field on the resource) β€” not the public `link_id` slug from the share URL.", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } }, { "name": "type", "in": "query", "description": "Return only one kind of activity.", "required": false, "schema": { "type": "string", "enum": [ "comment", "action" ] } } ], "responses": { "200": { "description": "Client activity retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkActivity" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkForbidden" } } } }, "404": { "description": "Share link not found in this workspace (`SHARE_LINK_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkNotFound" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/share-links/{link_id}/send-invitations": { "post": { "tags": [ "πŸ”— Share Links" ], "summary": "Send approval invitations", "description": "Enable the external-approval flow and email an approval link to each address. Re-sending to an address that was already invited is allowed and treated as a resend β€” note that it ROTATES that address's token, so any link previously emailed to them stops working.", "operationId": "sendShareLinkInvitations", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "link_id", "in": "path", "description": "The share link record id (the `id` field on the resource) β€” not the public `link_id` slug from the share URL.", "required": true, "schema": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "approval_emails", "approval_option" ], "properties": { "approval_emails": { "description": "No case-insensitive duplicates.", "type": "array", "items": { "type": "string", "format": "email", "example": "client@example.com" }, "maxItems": 10, "minItems": 1 }, "approval_option": { "description": "`anyone` clears on the first approval; `everyone` needs all of them.", "type": "string", "enum": [ "anyone", "everyone" ], "example": "anyone" } }, "type": "object" } } } }, "responses": { "200": { "description": "Invitations sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkInvitationsSent" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkUnauthorized" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkForbidden" } } } }, "404": { "description": "Share link not found in this workspace (`SHARE_LINK_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkNotFound" } } } }, "422": { "description": "Validation failed (`VALIDATION_ERROR`) or the send failed (`SHARE_LINK_INVITE_FAILED`)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ShareLinkValidationError" }, { "$ref": "#/components/schemas/ShareLinkWriteFailed" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLinkRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/team-members": { "get": { "tags": [ "πŸ‘₯ Team Members" ], "summary": "Get workspace team members", "description": "Retrieve a paginated list of team members for a specific workspace. Useful for selecting approvers when creating posts with approval workflows.", "operationId": "getTeamMembers", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "search", "in": "query", "description": "Search term to filter members by name or email", "required": false, "schema": { "type": "string", "example": "john" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (max: 100)", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "example": 10 } } ], "responses": { "200": { "description": "Team members retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Team members retrieved successfully" }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 5 }, "last_page": { "type": "integer", "example": 1 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 5 }, "data": { "type": "array", "items": { "properties": { "id": { "description": "The user's own id.", "type": "string", "example": "627a078300a7d866600e7d02" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "627a078300a7d866600e7d02", "deprecated": true }, "member_id": { "description": "The workspace membership id β€” use this as `member_id` when updating or removing this team member.", "type": "string", "example": "66a1f2e4c8b9a1234567890d" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "profile_picture": { "type": "string", "example": "https://example.com/avatar.jpg", "nullable": true }, "role": { "type": "string", "example": "admin" }, "membership": { "type": "string", "example": "member", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to workspace" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸ‘₯ Team Members" ], "summary": "Invite a team member", "description": "Invite a member to a workspace by email, with a role and permissions. Owner/admin only.", "operationId": "createTeamMember", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "role", "email" ], "properties": { "role": { "type": "string", "enum": [ "admin", "approver", "collaborator" ], "example": "collaborator" }, "membership": { "type": "string", "enum": [ "team", "client" ], "example": "team" }, "email": { "type": "string", "format": "email", "example": "member@example.com" }, "permissions": { "description": "Permission flags + per-platform account-id arrays. Booleans: addBlog, addSocial, addSource, addTopic, viewTeam, postsReview, rescheduleQueue, hasBillingAccess, canDeleteWorkspace, accessSharedFolder, changeFBGroupPublishAs, approverCanEditPost, approverCanAddNotes, approverCanCreatePost, allow_workflow_management. Arrays: facebook[], instagram[], twitter[], linkedin[], pinterest[], youtube[], tiktok[], threads[], bluesky[], gmb[], telegram[], wordpress[], medium[], shopify[], tumblr_blogs[], tumblr_profiles[], content_categories[].", "type": "object", "example": { "addSocial": true, "postsReview": true, "facebook": [ "298745546665028" ], "content_categories": [ "625d06734ceb636c2f5e7743" ] } } }, "type": "object" } } } }, "responses": { "201": { "description": "Invitation(s) sent" }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden: no permission to manage members (PermissionMiddleware, no error_code), or the plan's member limit is reached (TEAM_MEMBER_LIMIT_REACHED, with current_plan_limits) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" }, { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Team member limit reached for your plan." }, "error_code": { "type": "string", "example": "TEAM_MEMBER_LIMIT_REACHED" }, "current_plan_limits": { "type": "object", "example": { "members": 5, "used": 5 } } }, "type": "object" } ] } } } }, "422": { "description": "Validation failed (VALIDATION_ERROR, errors names each field), or the invite was refused by the product β€” e.g. the user is already a member (TEAM_MEMBER_ADD_FAILED, message carries the reason)", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed: The email must be a valid email address." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "email": [ "The email must be a valid email address." ] } } }, "type": "object" }, { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User is already a member of this workspace." }, "error_code": { "type": "string", "example": "TEAM_MEMBER_ADD_FAILED" } }, "type": "object" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/team-members/{member_id}": { "put": { "tags": [ "πŸ‘₯ Team Members" ], "summary": "Update a team member", "description": "Update a member's role and permissions. member_id is the membership id (member_id field from the list endpoint). Owner/admin only.", "operationId": "updateTeamMember", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "member_id", "in": "path", "description": "Membership id (member_id from the list endpoint)", "required": true, "schema": { "type": "string", "example": "6a212f2fd3c7bf8a640ce718" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "role", "permissions" ], "properties": { "role": { "type": "string", "enum": [ "admin", "approver", "collaborator" ], "example": "approver" }, "membership": { "type": "string", "enum": [ "team", "client" ], "example": "team" }, "permissions": { "description": "Same permission structure as create.", "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Member updated", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Team member updated successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No permission to manage members, or the member is the workspace super admin. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No permission to manage members" }, "error_code": { "description": "Set when member_id is the workspace super admin, who cannot be edited.", "type": "string", "example": "SUPER_ADMIN_NOT_EDITABLE" } }, "type": "object" } } } }, "422": { "description": "Validation failed / update failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸ‘₯ Team Members" ], "summary": "Remove a team member", "description": "Remove a member from a workspace. member_id is the membership id (member_id field from the list endpoint). If the member is part of approval workflows or in-flight posts, the call returns 422 REQUIRES_REMOVAL_CONFIRMATION until you resend with confirmed=true. Owner/admin only.", "operationId": "deleteTeamMember", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "member_id", "in": "path", "description": "Membership id (member_id from the list endpoint)", "required": true, "schema": { "type": "string", "example": "6a212ef8d3c7bf8a640ce716" } }, { "name": "confirmed", "in": "query", "description": "Set true to confirm removal when the member is in approval workflows / in-flight posts", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Member removed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Team member removed successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No permission to manage members, or the member is the workspace super admin. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No permission to manage members" }, "error_code": { "description": "Set when member_id is the workspace super admin, who cannot be removed.", "type": "string", "example": "SUPER_ADMIN_NOT_REMOVABLE" } }, "type": "object" } } } }, "422": { "description": "Removal not allowed / confirmation required (REQUIRES_REMOVAL_CONFIRMATION)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This member is part of approval workflows or in-flight posts. Resend with confirmed=true to proceed." }, "error_code": { "type": "string", "example": "REQUIRES_REMOVAL_CONFIRMATION" }, "context": { "type": "object" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/team-members/{member_id}/social-accounts": { "get": { "tags": [ "πŸ‘₯ Team Members" ], "summary": "Get a team member's social account access", "description": "List the social accounts a team member may use. `member_id` is the membership id (the `member_id` field from the team-members list endpoint). Members with the `admin` or `super_admin` role reach every connected account regardless of their grants; for them `has_access_to_all_accounts` is true and `accounts` lists the whole workspace. A grant outlives the account it points at: if an account is later disconnected its identifier is still reported, with `platform`, `name`, `profile_picture` and `type` all null, so reading this set and writing it back never silently revokes access. Requires the `update_member` permission (owner/admin).", "operationId": "getTeamMemberSocialAccounts", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "member_id", "in": "path", "description": "Membership id (member_id from the list endpoint)", "required": true, "schema": { "type": "string", "example": "6a212f2fd3c7bf8a640ce718" } } ], "responses": { "200": { "description": "Social account access retrieved", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Team member social account access retrieved successfully." }, "data": { "properties": { "member_id": { "type": "string", "example": "6a212f2fd3c7bf8a640ce718" }, "user_id": { "type": "string", "example": "627a078300a7d866600e7d02", "nullable": true }, "role": { "type": "string", "example": "collaborator", "nullable": true }, "has_access_to_all_accounts": { "description": "True for admin/super_admin, who bypass per-account grants.", "type": "boolean", "example": false }, "accounts": { "type": "array", "items": { "properties": { "id": { "description": "platform_identifier - the same id used in accounts[] when creating a post.", "type": "string", "example": "298745546665028" }, "platform": { "type": "string", "example": "facebook", "nullable": true }, "name": { "type": "string", "example": "ContentStudio Page", "nullable": true }, "profile_picture": { "type": "string", "example": "https://example.com/avatar.jpg", "nullable": true }, "type": { "type": "string", "example": "Page", "nullable": true }, "permission_key": { "description": "The accounts key this grant is stored under. Differs from platform for Tumblr, whose profiles live under tumblr_profiles.", "type": "string", "example": "facebook", "nullable": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No permission to manage members. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Team member not found (TEAM_MEMBER_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Team member not found." }, "error_code": { "type": "string", "example": "TEAM_MEMBER_NOT_FOUND" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "πŸ‘₯ Team Members" ], "summary": "Set a team member's social account access", "description": "Grant or revoke the social accounts a team member may use, in one call. `member_id` is the membership id (the `member_id` field from the team-members list endpoint). SEMANTICS: each key of `accounts` is set to exactly the ids you send, so one call both adds and removes; a platform key you omit is left untouched; a key sent as an empty array clears that platform. Boolean permission flags and role are never read or written here - use the PUT team-members/{member_id} endpoint for those. IDS: send `platform_identifier` values, the same ids the accounts endpoint returns and that `accounts[]` takes when creating a post. Tumblr profiles go under `tumblr_profiles`; Pinterest grants are the profile id, not a board id. REVOKING ACCESS DOES NOT TOUCH POSTS THE MEMBER ALREADY SCHEDULED: those posts stay scheduled and still publish at their scheduled time, the member simply stops seeing and being able to edit them. This matches the web app exactly - there is no cascade into scheduled posts. Setting access for an `admin` or `super_admin` member is refused with `ROLE_BYPASSES_ACCOUNT_ACCESS`: those roles reach every connected account regardless of grants, so storing one would have no effect. Requires the `update_member` permission (owner/admin).", "operationId": "updateTeamMemberSocialAccounts", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "member_id", "in": "path", "description": "Membership id (member_id from the list endpoint)", "required": true, "schema": { "type": "string", "example": "6a212f2fd3c7bf8a640ce718" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "accounts" ], "properties": { "accounts": { "description": "Platform permission key to list of platform_identifier values. Allowed keys: facebook, instagram, threads, twitter, linkedin, pinterest, telegram, youtube, tiktok, bluesky, gmb, tumblr, tumblr_profiles.", "type": "object", "example": { "facebook": [ "298745546665028", "104782918283746" ], "instagram": [ "17841400000000000" ], "linkedin": [] } } }, "type": "object" } } } }, "responses": { "200": { "description": "Access updated - the response echoes the member's full resulting access set", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Team member social account access updated successfully." }, "data": { "properties": { "member_id": { "type": "string", "example": "6a212f2fd3c7bf8a640ce718" }, "user_id": { "type": "string", "example": "627a078300a7d866600e7d02", "nullable": true }, "role": { "type": "string", "example": "collaborator", "nullable": true }, "has_access_to_all_accounts": { "description": "True for admin/super_admin, who bypass per-account grants.", "type": "boolean", "example": false }, "accounts": { "type": "array", "items": { "properties": { "id": { "description": "platform_identifier - the same id used in accounts[] when creating a post.", "type": "string", "example": "298745546665028" }, "platform": { "type": "string", "example": "facebook", "nullable": true }, "name": { "type": "string", "example": "ContentStudio Page", "nullable": true }, "profile_picture": { "type": "string", "example": "https://example.com/avatar.jpg", "nullable": true }, "type": { "type": "string", "example": "Page", "nullable": true }, "permission_key": { "description": "The accounts key this grant is stored under. Differs from platform for Tumblr, whose profiles live under tumblr_profiles.", "type": "string", "example": "facebook", "nullable": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No permission to manage members. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`, `ACCOUNT_ACCESS_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Team member not found (TEAM_MEMBER_NOT_FOUND)", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Team member not found." }, "error_code": { "type": "string", "example": "TEAM_MEMBER_NOT_FOUND" } }, "type": "object" } } } }, "422": { "description": "Validation failed. error_code is one of VALIDATION_ERROR, INVALID_ACCOUNT_ID, ACCOUNT_NOT_ACCESSIBLE, ROLE_BYPASSES_ACCOUNT_ACCESS, TEAM_MEMBER_SOCIAL_ACCESS_UPDATE_FAILED. A refusal writes nothing.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The account 999 in facebook is not a connected account in this workspace." }, "error_code": { "type": "string", "example": "INVALID_ACCOUNT_ID" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/me": { "get": { "tags": [ "πŸ‘€ Authentication" ], "summary": "Get authenticated user information", "description": "Retrieve information about the currently authenticated user. This is typically the first endpoint you'll call to verify your API key is working correctly.", "operationId": "getMe", "responses": { "429": { "description": "Too Many Requests - Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "description": "Request limit per time window", "schema": { "type": "integer", "example": 100 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets", "schema": { "type": "integer", "example": 1642694400 } }, "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 }, "reset_time": { "type": "integer", "example": 1642694400 } }, "type": "object" } } } }, "200": { "description": "User information retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User information retrieved successfully" }, "data": { "properties": { "id": { "type": "string", "example": "64a1b2c3d4e5f6789012345" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "64a1b2c3d4e5f6789012345", "deprecated": true }, "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Doe" }, "full_name": { "type": "string", "example": "John Doe" }, "username": { "type": "string", "example": "johndoe" }, "email": { "type": "string", "example": "john@example.com" }, "phone_no": { "type": "string", "example": "+1234567890" }, "image": { "type": "string", "example": "/uploads/profile/user.jpg" }, "state": { "type": "string", "example": "active" }, "date_format": { "type": "string", "example": "Y-m-d" }, "time_format": { "type": "string", "example": "H:i:s" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" }, "authenticated_at": { "type": "string", "format": "date-time", "example": "2024-01-20T14:25:30.000Z" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" }, "errors": { "type": "array", "items": { "type": "string", "example": "Invalid API key" } } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong." }, "errors": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/webhooks/event-types": { "get": { "tags": [ "πŸͺ Webhooks" ], "summary": "List subscribable webhook event types", "description": "Every event a webhook can subscribe to, with when it fires and the OpenAPI component (`payload_schema`) describing the event's `data` object. Every delivery wraps `data` in the same envelope β€” see `WebhookEnvelope`.", "operationId": "listWebhookEventTypes", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Any workspace you are a member of. It selects whose API credits the call uses; webhooks themselves belong to you, not to the workspace.", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Event types retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventTypeList" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnauthorized" } } } }, "403": { "description": "Not a member of the workspace, the workspace is locked, its plan has no API access (`API_ACCESS_NOT_ALLOWED`) or its API credits are used up (`API_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookForbidden" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWorkspaceNotFound" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/webhooks": { "get": { "tags": [ "πŸͺ Webhooks" ], "summary": "List webhooks", "description": "The API key owner's webhooks, newest first, with how many of the per-user allowance are used. Signing secrets are never returned β€” `has_secret` says whether one is set.", "operationId": "listWebhooks", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Any workspace you are a member of. It selects whose API credits the call uses; webhooks themselves belong to you, not to the workspace.", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "responses": { "200": { "description": "Webhooks retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnauthorized" } } } }, "403": { "description": "Not a member of the workspace, the workspace is locked, its plan has no API access (`API_ACCESS_NOT_ALLOWED`) or its API credits are used up (`API_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookForbidden" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWorkspaceNotFound" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRateLimited" } } } }, "500": { "description": "Unexpected failure (`WEBHOOK_REQUEST_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequestFailed" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "πŸͺ Webhooks" ], "summary": "Create a webhook", "description": "Registers an HTTPS endpoint for the chosen events. Before saving, ContentStudio refuses URLs that resolve to a private, loopback, link-local or reserved address (`WEBHOOK_URL_NOT_ALLOWED`) and then sends one signed `webhook.ping` event to the URL; anything other than a 2xx within 5 seconds refuses the webhook (`WEBHOOK_PREFLIGHT_FAILED`). A `whsec_` signing secret is generated when none is supplied, and is returned in this response only β€” store it now, it cannot be read again.", "operationId": "createWebhook", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Any workspace you are a member of. It selects whose API credits the call uses; webhooks themselves belong to you, not to the workspace.", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequest" } } } }, "responses": { "201": { "description": "Webhook created; the signing secret is in `data.secret`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnauthorized" } } } }, "403": { "description": "Not a member of the workspace, the workspace is locked, its plan has no API access (`API_ACCESS_NOT_ALLOWED`) or its API credits are used up (`API_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookForbidden" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWorkspaceNotFound" } } } }, "422": { "description": "Validation failed (`VALIDATION_ERROR`), allowance used up (`WEBHOOK_LIMIT_REACHED`), internal URL (`WEBHOOK_URL_NOT_ALLOWED`) or the endpoint did not answer the ping (`WEBHOOK_PREFLIGHT_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnprocessable" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRateLimited" } } } }, "500": { "description": "Unexpected failure (`WEBHOOK_REQUEST_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequestFailed" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/webhooks/{webhook_id}": { "get": { "tags": [ "πŸͺ Webhooks" ], "summary": "Get a webhook", "operationId": "getWebhook", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Any workspace you are a member of. It selects whose API credits the call uses; webhooks themselves belong to you, not to the workspace.", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "webhook_id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "string", "example": "66f1c2a9e4b0a1b2c3d4e5f6" } } ], "responses": { "200": { "description": "Webhook retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookFetched" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnauthorized" } } } }, "403": { "description": "Not a member of the workspace, the workspace is locked, its plan has no API access (`API_ACCESS_NOT_ALLOWED`) or its API credits are used up (`API_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookForbidden" } } } }, "404": { "description": "Workspace not found, or no webhook with this ID belongs to the key's user (`WEBHOOK_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookNotFound" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "put": { "tags": [ "πŸͺ Webhooks" ], "summary": "Update, disable or re-enable a webhook", "description": "Partial update β€” only the fields sent are changed. Send `status: disabled` to pause deliveries and `status: enabled` to resume them; a webhook ContentStudio disabled after repeated failures (`disabled_by_system`) is re-enabled the same way. A new `url` goes through the same internal-address check and ping as create.", "operationId": "updateWebhook", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Any workspace you are a member of. It selects whose API credits the call uses; webhooks themselves belong to you, not to the workspace.", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "webhook_id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "string", "example": "66f1c2a9e4b0a1b2c3d4e5f6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdateRequest" } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnauthorized" } } } }, "403": { "description": "Not a member of the workspace, the workspace is locked, its plan has no API access (`API_ACCESS_NOT_ALLOWED`) or its API credits are used up (`API_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookForbidden" } } } }, "404": { "description": "Workspace not found, or no webhook with this ID belongs to the key's user (`WEBHOOK_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookNotFound" } } } }, "422": { "description": "Validation failed (`VALIDATION_ERROR`), internal URL (`WEBHOOK_URL_NOT_ALLOWED`) or the new URL did not answer the ping (`WEBHOOK_PREFLIGHT_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnprocessable" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRateLimited" } } } }, "500": { "description": "Unexpected failure (`WEBHOOK_REQUEST_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequestFailed" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "πŸͺ Webhooks" ], "summary": "Delete a webhook", "description": "Stops all deliveries to the webhook immediately and frees one place in the per-user allowance.", "operationId": "deleteWebhook", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Any workspace you are a member of. It selects whose API credits the call uses; webhooks themselves belong to you, not to the workspace.", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "webhook_id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "string", "example": "66f1c2a9e4b0a1b2c3d4e5f6" } } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeleted" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnauthorized" } } } }, "403": { "description": "Not a member of the workspace, the workspace is locked, its plan has no API access (`API_ACCESS_NOT_ALLOWED`) or its API credits are used up (`API_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookForbidden" } } } }, "404": { "description": "Workspace not found, or no webhook with this ID belongs to the key's user (`WEBHOOK_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookNotFound" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/webhooks/{webhook_id}/rotate-secret": { "post": { "tags": [ "πŸͺ Webhooks" ], "summary": "Rotate a webhook's signing secret", "description": "Generates a new signing secret and returns it once. The previous secret is not revoked straight away: until `previous_secret_expires_at` (24 hours) every delivery carries two signatures in `x-contentstudio-signature`, one per secret (`v1, v1,`). Verifiers that accept any matching signature keep working with either secret, so deploy the new secret within the window and no delivery is missed. Rotating a webhook that had no secret starts signing it; `previous_secret_expires_at` is then null.", "operationId": "rotateWebhookSecret", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Any workspace you are a member of. It selects whose API credits the call uses; webhooks themselves belong to you, not to the workspace.", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "webhook_id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "string", "example": "66f1c2a9e4b0a1b2c3d4e5f6" } } ], "responses": { "200": { "description": "Secret rotated; the new secret is in `data.secret`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretRotated" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnauthorized" } } } }, "403": { "description": "Not a member of the workspace, the workspace is locked, its plan has no API access (`API_ACCESS_NOT_ALLOWED`) or its API credits are used up (`API_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookForbidden" } } } }, "404": { "description": "Workspace not found, or no webhook with this ID belongs to the key's user (`WEBHOOK_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookNotFound" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRateLimited" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "πŸͺ Webhooks" ], "summary": "List a webhook's deliveries", "description": "One row per event sent to the webhook, newest first. Retries are collapsed: each row shows the latest attempt, so `outcome` is the event's current state β€” `delivered`, `failed` (retries exhausted or a non-retryable 4xx), `retrying` (another attempt is scheduled) or `skipped_out_of_credits` (not sent because the API credit pool was used up). `is_test` marks test sends from the settings screen. Deliveries are kept for 30 days.", "operationId": "listWebhookDeliveries", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Any workspace you are a member of. It selects whose API credits the call uses; webhooks themselves belong to you, not to the workspace.", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, { "name": "webhook_id", "in": "path", "description": "Webhook ID", "required": true, "schema": { "type": "string", "example": "66f1c2a9e4b0a1b2c3d4e5f6" } }, { "name": "status", "in": "query", "description": "`successful` = delivered only; `failed` = failed only; `all` (default) includes retrying and skipped deliveries too.", "required": false, "schema": { "type": "string", "default": "all", "enum": [ "all", "successful", "failed" ] } }, { "name": "event_type", "in": "query", "description": "Only deliveries of this event type.", "required": false, "schema": { "type": "string", "example": "post.published" } }, { "name": "from", "in": "query", "description": "Only deliveries at or after this time. ISO 8601; read as UTC when no offset is given.", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2026-10-01T00:00:00Z" } }, { "name": "to", "in": "query", "description": "Only deliveries at or before this time. ISO 8601; read as UTC when no offset is given.", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2026-10-06T23:59:59Z" } }, { "name": "search", "in": "query", "description": "An exact event ID, or part of an event type.", "required": false, "schema": { "type": "string", "example": "01J9Z3W4QK8X6M2N5P7R9T1V3B" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Deliveries retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnauthorized" } } } }, "403": { "description": "Not a member of the workspace, the workspace is locked, its plan has no API access (`API_ACCESS_NOT_ALLOWED`) or its API credits are used up (`API_CREDIT_LIMIT_EXCEEDED`) Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookForbidden" } } } }, "404": { "description": "Workspace not found, or no webhook with this ID belongs to the key's user (`WEBHOOK_NOT_FOUND`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookNotFound" } } } }, "422": { "description": "Invalid filter (`VALIDATION_ERROR`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUnprocessable" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRateLimited" } } } }, "500": { "description": "Unexpected failure (`WEBHOOK_REQUEST_FAILED`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequestFailed" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces": { "get": { "tags": [ "🏒 Workspaces" ], "summary": "Get user workspaces", "description": "Returns paginated workspaces associated with the authenticated user", "operationId": "bc407c86240418a5683d458d2efb23fc", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Workspaces retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workspaces retrieved successfully" }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 25 }, "last_page": { "type": "integer", "example": 3 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 10 }, "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "610a1e660cb41530ca40d372" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "610a1e660cb41530ca40d372", "deprecated": true }, "name": { "type": "string", "example": "Hello Support" }, "slug": { "type": "string", "example": "topviewsports" }, "timezone": { "type": "string", "example": "Australia/Adelaide" }, "logo": { "type": "string", "example": "https://storage.googleapis.com/.../settings/XfEEs26zMaTNdlczyHwp.jpg" }, "created_at": { "type": "string", "format": "date-time", "example": "2021-08-04T04:58:14.000000Z" }, "company_name": { "type": "string", "example": "Topviewsports" }, "company_logo": { "type": "string", "example": "https://storage.googleapis.com/.../analytics/companies/2J34kSrkU7GwqrUqshYe.jpg" }, "policy": { "properties": { "can_edit": { "type": "boolean", "example": false }, "can_remove": { "type": "boolean", "example": false } }, "type": "object" }, "on_hold": { "type": "boolean", "example": false } }, "type": "object" } } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "description": "Request limit per time window", "schema": { "type": "integer", "example": 100 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Unix timestamp when rate limit resets", "schema": { "type": "integer", "example": 1642694400 } }, "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 }, "reset_time": { "type": "integer", "example": 1642694400 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "post": { "tags": [ "🏒 Workspaces" ], "summary": "Create a workspace", "description": "Creates a new workspace owned by the authenticated user. Subject to the plan's workspace limit.\n *\n * `timezone` accepts any IANA identifier plus the legacy aliases the product accepts (`US/Pacific`, `US/Eastern`, `America/Buenos_Aires`, `MST7MDT`, …); an alias is stored in canonical form and the canonical value is returned. An unrecognised identifier is rejected with 422.", "operationId": "6a5cbee2446f30a752364ff3138c00dd", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "logo", "timezone" ], "properties": { "name": { "type": "string", "maxLength": 35, "example": "Acme Marketing" }, "logo": { "type": "string", "format": "url", "example": "https://logo.clearbit.com/contentstudio.io" }, "timezone": { "type": "string", "example": "Asia/Karachi" }, "super_admin_id": { "description": "Account owner to create the workspace under. Optional when you are the account owner or are linked to exactly one super admin; required when you manage multiple super admins.", "type": "string", "example": "610a1d92b11ba161ce1cd372", "nullable": true }, "note": { "type": "string", "example": "Client workspace", "nullable": true }, "instagram_posting_method": { "type": "string", "enum": [ "api", "mobile" ], "example": "api" }, "first_day": { "properties": { "day": { "type": "string", "example": "Monday" }, "key": { "type": "integer", "example": 1 } }, "type": "object" }, "company_name": { "description": "Report branding name, shown on generated reports and white-labelled dashboards.", "type": "string", "maxLength": 100, "example": "Acme Inc", "nullable": true }, "company_logo": { "description": "Report branding logo. Upload bytes via POST /workspaces/{workspace_id}/media and pass the returned URL.", "type": "string", "format": "url", "example": "https://storage.googleapis.com/lumotive-web-storage/analytics/companies/610a1d92b11ba161ce1cd372/company.jpg", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Workspace created successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workspace created successfully. Use the returned `id` as `workspace_id` in subsequent requests." }, "data": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden: the plan's workspace limit is reached (WORKSPACE_LIMIT_REACHED), the owner's trial has expired (WORKSPACE_TRIAL_EXPIRED), super_admin_id names an account the caller may not create workspaces for (INVALID_SUPER_ADMIN), or the caller is neither an admin of an owner's workspace nor on a plan of their own (WORKSPACE_CREATE_NOT_ALLOWED)", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace limit reached for your plan." }, "error_code": { "type": "string", "example": "WORKSPACE_LIMIT_REACHED" } }, "type": "object" }, { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Your trial period has expired." }, "error_code": { "type": "string", "example": "WORKSPACE_TRIAL_EXPIRED" } }, "type": "object" }, { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Super Admin." }, "error_code": { "type": "string", "example": "INVALID_SUPER_ADMIN" } }, "type": "object" }, { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You can only create a workspace on a plan of your own or as an admin of the owner's workspaces." }, "error_code": { "type": "string", "example": "WORKSPACE_CREATE_NOT_ALLOWED" } }, "type": "object" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed: The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ] } } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}": { "put": { "tags": [ "🏒 Workspaces" ], "summary": "Update a workspace", "description": "Updates an existing workspace. Only the provided fields are changed; omitted fields keep their current values.\n *\n * **Timezone.** `timezone` accepts any IANA identifier plus the legacy aliases the product accepts (`US/Pacific`, `US/Eastern`, `America/Buenos_Aires`, `MST7MDT`, …), stored in canonical form. An unrecognised identifier is rejected with 422 and the stored value is left untouched.\n *\n * **Changing the timezone does NOT reschedule anything.** A post's publish time is stored in UTC and the scheduler compares it against the current UTC time, so an already-scheduled post fires at exactly the same instant as before β€” only its rendered local time moves. A post scheduled for 15:00 Asia/Karachi (10:00 UTC) still publishes at 10:00 UTC after switching to America/New_York, but now shows as 06:00 in the calendar.\n *\n * Because of that, any update that actually changes the timezone returns an extra top-level `timezone_change` object stating the effect and counting the pending scheduled posts whose displayed time shifts. The object is **absent** when the timezone is unchanged or not supplied. To move posts to the same local time in the new timezone, reschedule them explicitly with `PUT /api/v1/posts/{post_id}`.", "operationId": "77afb8c7d9d2e756ed38521db17f85b3", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "64edbecf78f9fa920f0279fe" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 35, "example": "Acme Marketing" }, "logo": { "type": "string", "format": "url", "example": "https://logo.clearbit.com/contentstudio.io" }, "timezone": { "type": "string", "example": "Asia/Karachi" }, "note": { "type": "string", "example": "Updated note", "nullable": true }, "instagram_posting_method": { "type": "string", "enum": [ "api", "mobile" ], "example": "api" }, "first_day": { "properties": { "day": { "type": "string", "example": "Monday" }, "key": { "type": "integer", "example": 1 } }, "type": "object" }, "company_name": { "description": "Report branding name, shown on generated reports and white-labelled dashboards.", "type": "string", "maxLength": 100, "example": "Acme Inc", "nullable": true }, "company_logo": { "description": "Report branding logo. Upload bytes via POST /workspaces/{workspace_id}/media and pass the returned URL.", "type": "string", "format": "url", "example": "https://storage.googleapis.com/lumotive-web-storage/analytics/companies/610a1d92b11ba161ce1cd372/company.jpg", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Workspace updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workspace updated successfully. Use the returned `id` as `workspace_id` in subsequent requests." }, "data": { "type": "object" }, "timezone_change": { "description": "Present ONLY when this request changed the EFFECTIVE timezone. Absent when the timezone is unchanged, not supplied, or when only the alias form differs (US/Pacific to America/Los_Angeles is the same zone). `from` and `to` are always canonical identifiers.", "properties": { "from": { "description": "Canonical identifier of the previous timezone.", "type": "string", "example": "Asia/Karachi" }, "to": { "type": "string", "example": "America/New_York" }, "scheduled_posts_affected": { "description": "Pending scheduled posts whose DISPLAYED time shifts. None of them were rescheduled β€” their UTC publish time is unchanged.", "type": "integer", "example": 12 }, "notice": { "type": "string", "example": "Already-scheduled posts keep their original publish time in UTC and will publish at the same moment as before. Only their displayed time changes: a post set for 15:00 Asia/Karachi now shows as 06:00 America/New_York. No post was rescheduled." } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No permission to update this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No permission to update this workspace" } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found" } }, "type": "object" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] }, "delete": { "tags": [ "🏒 Workspaces" ], "summary": "Delete a workspace", "description": "Soft-deletes a workspace and schedules permanent removal. The owner of the only default workspace cannot delete it.", "operationId": "197d3c7363d303e58a2be35b9f192cc3", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "64edbecf78f9fa920f0279fe" } } ], "responses": { "200": { "description": "Workspace deleted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workspace deleted successfully." } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No permission to delete this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No permission to delete this workspace" } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found" } }, "type": "object" } } } }, "422": { "description": "Workspace cannot be deleted", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace cannot be deleted" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/settings": { "get": { "tags": [ "🏒 Workspaces" ], "summary": "Read workspace settings", "description": "Returns every workspace-level setting the product exposes, plus the workspace's posting state and the number of scheduled posts currently held by a pause.", "operationId": "650653d813bf84a2ac1f9017afb0c4cf", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "64edbecf78f9fa920f0279fe" } } ], "responses": { "200": { "description": "Workspace settings retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Workspace settings retrieved successfully." }, "data": { "properties": { "id": { "type": "string", "example": "64edbecf78f9fa920f0279fe" }, "name": { "type": "string", "example": "Acme Marketing" }, "slug": { "type": "string", "example": "acme-marketing" }, "logo": { "type": "string", "format": "url", "example": "https://storage.googleapis.com/lumotive-web-storage/settings/610a1d92b11ba161ce1cd372/logo.jpg" }, "timezone": { "type": "string", "example": "Asia/Karachi" }, "first_day": { "properties": { "day": { "type": "string", "example": "Monday" }, "key": { "type": "integer", "example": 1 } }, "type": "object" }, "note": { "type": "string", "example": "Client workspace", "nullable": true }, "instagram_posting_method": { "type": "string", "enum": [ "api", "mobile" ], "example": "api" }, "company_name": { "type": "string", "example": "Acme Inc", "nullable": true }, "company_logo": { "type": "string", "format": "url", "example": "https://storage.googleapis.com/lumotive-web-storage/analytics/companies/610a1d92b11ba161ce1cd372/company.jpg", "nullable": true }, "posting": { "properties": { "paused": { "type": "boolean", "example": false }, "paused_posts_count": { "description": "Scheduled posts currently held by a pause. 0 when publishing is active.", "type": "integer", "example": 0 }, "paused_at": { "type": "string", "format": "date-time", "example": "2026-09-02T10:48:00+00:00", "nullable": true }, "resumed_at": { "type": "string", "format": "date-time", "example": "2026-08-30T09:12:44+00:00", "nullable": true }, "changed_by": { "type": "string", "example": "610a1d92b11ba161ce1cd372", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - No access to this workspace. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found." } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/posting/pause": { "post": { "tags": [ "🏒 Workspaces" ], "summary": "Pause publishing for a workspace", "description": "Holds every pending post in the workspace and stops publishing, exactly as the Pause Posting action in the web app does.\n *\n * **What is held:** posts that are `scheduled`, posts in `review` whose slot is still in the future, and `draft` posts awaiting approval. Each keeps its original status in `old_status` and becomes a `draft` flagged `on_hold`.\n *\n * **Side effect:** active RSS and Evergreen automations in the workspace are also locked. Resuming does **not** unlock them β€” see the resume endpoint.\n *\n * **Not held:** posts already published, failed, or rejected, and posts whose `review` slot has passed.\n *\n * The pause is visible in the web app, the mobile apps and the Chrome extension immediately: it writes the same `workspace.on_hold` flag they all read.\n *\n * Calling this on an already-paused workspace is safe β€” it holds anything scheduled since the last pause and returns the current count.", "operationId": "0379f47c14691794e0a0911b808459ce", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "64edbecf78f9fa920f0279fe" } } ], "responses": { "200": { "description": "Posting paused", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Posting paused for this workspace." }, "data": { "properties": { "paused": { "type": "boolean", "example": true }, "paused_posts_count": { "description": "Scheduled posts this pause is holding.", "type": "integer", "example": 12 }, "paused_at": { "type": "string", "format": "date-time", "example": "2026-09-02T10:48:00+00:00", "nullable": true }, "automations_locked": { "description": "RSS and Evergreen automations that were active and have now been locked.", "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Requires the save_workspace permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found." } }, "type": "object" } } } }, "422": { "description": "The pause could not be applied (WORKSPACE_PAUSE_FAILED). There is no request body, so this endpoint has no validation error.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to change the posting state for this workspace." }, "error_code": { "type": "string", "example": "WORKSPACE_PAUSE_FAILED" } }, "type": "object" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/api/v1/workspaces/{workspace_id}/posting/resume": { "post": { "tags": [ "🏒 Workspaces" ], "summary": "Resume publishing for a workspace", "description": "Releases the hold on the workspace and returns held posts to the state the product returns them to. `time_type` decides what happens to each held post:\n *\n * - `resume` (default, and the option the web app pre-selects) β€” a post whose scheduled slot is still in the future goes back to its original status. A post whose slot passed while publishing was paused stays a draft; it is **not** back-published.\n * - `recurring` β€” every held post goes back to its original status and is re-spread from now, one every `recurring.value` `recurring.type`.\n * - `custom` β€” the hold is released but every post stays a draft, for you to reschedule yourself.\n *\n * **Automations are not unlocked.** RSS and Evergreen automations locked by the pause stay locked, matching the product: a blanket unlock would also re-enable automations the customer had locked by hand, and some plans do not permit automations at all. Re-enable them individually.", "operationId": "bf7121239f07b8334e147fb1ea4e37f5", "parameters": [ { "name": "workspace_id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string", "example": "64edbecf78f9fa920f0279fe" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "time_type": { "type": "string", "default": "resume", "enum": [ "resume", "recurring", "custom" ], "example": "resume" }, "recurring": { "description": "Required when time_type is `recurring`.", "properties": { "type": { "type": "string", "enum": [ "hour", "day", "week" ], "example": "day" }, "value": { "type": "integer", "maximum": 52, "minimum": 1, "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Posting resumed", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Posting resumed for this workspace." }, "data": { "properties": { "paused": { "type": "boolean", "example": false }, "time_type": { "type": "string", "example": "resume" }, "posts_released": { "description": "Posts the hold was lifted from.", "type": "integer", "example": 12 }, "posts_restored": { "description": "Of those, how many are back at the status they held before the pause. A post that was awaiting approval as a draft and returns to draft counts here.", "type": "integer", "example": 9 }, "posts_left_as_draft": { "description": "The remainder: posts not back at their pre-pause status because their slot expired during the pause, or because time_type was `custom`.", "type": "integer", "example": 3 }, "resumed_at": { "type": "string", "format": "date-time", "example": "2026-09-02T11:02:00+00:00", "nullable": true }, "automations_unlocked": { "description": "Always false β€” see the endpoint description.", "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" } } } }, "403": { "description": "Forbidden - Requires the save_workspace permission. Workspace access refusals return `error_code` `WORKSPACE_ACCESS_DENIED`, `WORKSPACE_INVITATION_PENDING`, `WORKSPACE_LOCKED`, `PERMISSION_DENIED`.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found." } }, "type": "object" } } } }, "422": { "description": "Validation failed (VALIDATION_ERROR β€” time_type must be resume, recurring or custom; recurring needs type and value), or the resume could not be applied (WORKSPACE_RESUME_FAILED)", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The selected time type is invalid." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "time_type": [ "The selected time type is invalid." ] } } }, "type": "object" }, { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to change the posting state for this workspace." }, "error_code": { "type": "string", "example": "WORKSPACE_RESUME_FAILED" } }, "type": "object" } ] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } } }, "components": { "schemas": { "CarouselOptions": { "required": [ "prompt" ], "properties": { "prompt": { "description": "Public API v1 AI carousels (CONT-4215). Like image generation, generate and edit answer when the\ndeck is done: the slides in the media library, ready for POST .../posts as a carousel.", "type": "string", "maxLength": 2000, "example": "5 tips for better LinkedIn headlines" }, "slide_count": { "description": "Omit it and the AI chooses the length, as in AI chat.", "type": "integer", "maximum": 10, "minimum": 3, "nullable": true }, "size": { "description": "portrait is 4:5 (1080x1350), square is 1:1 (1080x1080).", "type": "string", "default": "portrait", "enum": [ "portrait", "square" ] }, "language": { "description": "The language of the slides and caption. Defaults to the request locale.", "type": "string", "example": "English", "nullable": true }, "use_brand": { "description": "Brand knowledge (voice, logo, handle). Omitted follows the workspace setting; true or false overrides it for this request. The response reports brand_applied.", "type": "boolean", "nullable": true }, "style": { "description": "Omit it for mode auto: the AI picks the look and the request never stops to ask. Each mode reads its own fields: template reads template_id, custom reads description and/or references, auto reads neither; any of them sent with another mode is refused with STYLE_FIELDS_CONFLICT. brand_colours works with every mode.", "properties": { "mode": { "type": "string", "default": "auto", "enum": [ "auto", "template", "custom" ] }, "template_id": { "description": "Required with mode template. An id from GET .../ai/carousels/templates.", "type": "string", "example": "clean-minimal", "nullable": true }, "description": { "description": "With mode custom: the look in plain words.", "type": "string", "maxLength": 1000, "example": "dark mode, neon accents", "nullable": true }, "references": { "description": "With mode custom: up to 2 images to match, as workspace media IDs or public image URLs.", "type": "array", "items": { "type": "string" }, "maxItems": 2, "nullable": true }, "brand_colours": { "description": "false keeps the template's own colours (the logo stays when use_brand is on).", "type": "boolean", "default": true } }, "type": "object", "nullable": true } }, "type": "object" }, "CarouselDeck": { "properties": { "carousel_id": { "description": "Use this with POST .../ai/carousels/{carousel_id}/edit.", "type": "string", "example": "crs_4f1c..." }, "slides": { "description": "In order. Each is in the workspace media library.", "type": "array", "items": { "properties": { "position": { "type": "integer", "example": 1 }, "slot": { "description": "0-based place in the planned deck; differs from position after a failed slide.", "type": "integer", "example": 0 }, "media_id": { "type": "string" }, "url": { "type": "string", "format": "url" }, "width": { "type": "integer", "example": 1080 }, "height": { "type": "integer", "example": 1350 } }, "type": "object" } }, "caption": { "type": "string" }, "style": { "description": "The look used: route (template, custom, photo or drawn), template_id, brand_colours.", "type": "object" }, "slide_count": { "description": "Slides planned.", "type": "integer", "example": 6 }, "aspect_ratio": { "type": "string", "example": "4:5" }, "failed_slots": { "description": "Planned slots that could not be drawn, not charged.", "type": "array", "items": { "type": "integer" } }, "notes": { "type": "string" }, "credits": { "description": "Image credits charged.", "type": "integer", "example": 8 }, "brand_applied": { "type": "boolean" } }, "type": "object" }, "CarouselError": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string" }, "error_code": { "type": "string", "example": "UNKNOWN_TEMPLATE" }, "detail": { "description": "The AI service's own explanation, when it gave one.", "type": "string", "nullable": true }, "errors": { "description": "Field-level messages, on VALIDATION_ERROR.", "type": "object", "example": { "prompt": [ "The prompt field is required." ] }, "nullable": true } }, "type": "object" }, "AnalyticsUnauthorized": { "properties": { "status": { "description": "Reusable OpenAPI schemas for the public-API analytics responses.\n\nThese are referenced from individual controller methods via\n`@OA\\JsonContent(ref=\"#/components/schemas/\")` to avoid\nduplicating the same envelope examples on every endpoint.", "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" }, "AnalyticsForbidden": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You do not have access to this workspace." } }, "type": "object" }, "AnalyticsValidationError": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "platform_id": [ "The platform id field is required." ], "start_date": [ "The start date is not a valid date." ] } } }, "type": "object" }, "AnalyticsRateLimited": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" }, "AnalyticsUpstreamError": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "We couldn't load your analytics right now. Please try again." }, "error_code": { "type": "string", "example": "ANALYTICS_UPSTREAM_ERROR" }, "upstream_status": { "type": "integer", "example": 503 } }, "type": "object" }, "CampaignLabelScopeBody": { "description": "At least one of `campaigns` or `labels` must be present and non-empty. Omitting every `*_accounts` array means every supported account in the workspace.", "required": [ "start_date", "end_date" ], "properties": { "start_date": { "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-01-31" }, "campaigns": { "type": "array", "items": { "type": "string" }, "example": [ "64f0a1b2c3d4e5f60718293a" ] }, "labels": { "type": "array", "items": { "type": "string" }, "example": [] }, "timezone": { "type": "string", "default": "UTC", "example": "America/New_York" }, "facebook_accounts": { "type": "array", "items": { "type": "string" }, "example": [ "104857392012345" ] }, "instagram_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "linkedin_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "tiktok_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "youtube_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "pinterest_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "twitter_accounts": { "description": "X (Twitter) user IDs. X reports impressions but no unique-reach metric.", "type": "array", "items": { "type": "string" }, "example": [] } }, "type": "object" }, "CampaignLabelPostsBody": { "required": [ "start_date", "end_date" ], "properties": { "start_date": { "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-01-31" }, "campaigns": { "type": "array", "items": { "type": "string" }, "example": [ "64f0a1b2c3d4e5f60718293a" ] }, "labels": { "type": "array", "items": { "type": "string" }, "example": [] }, "timezone": { "type": "string", "default": "UTC", "example": "America/New_York" }, "facebook_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "instagram_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "linkedin_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "tiktok_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "youtube_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "pinterest_accounts": { "type": "array", "items": { "type": "string" }, "example": [] }, "twitter_accounts": { "description": "X (Twitter) user IDs. Reach is null in the Posts table; it substitutes to impressions for ranking only.", "type": "array", "items": { "type": "string" }, "example": [] }, "platforms": { "description": "Networks to include. Empty or omitted means every network the account selection enables.", "type": "array", "items": { "type": "string", "enum": [ "facebook", "instagram", "linkedin", "tiktok", "youtube", "pinterest", "twitter" ] }, "example": [ "facebook", "instagram" ] }, "search": { "description": "Case-insensitive caption match.", "type": "string", "maxLength": 200, "example": "launch" }, "sort_by": { "type": "string", "default": "engagement", "enum": [ "engagement", "views", "impressions", "reach", "link_clicks", "video_views", "likes", "comments", "shares", "saves", "published_at", "caption", "post_type" ] }, "sort_order": { "type": "string", "default": "desc", "enum": [ "desc", "asc" ] }, "limit": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } }, "type": "object" }, "CampaignLabelBreakdownEntity": { "description": "One campaign or label with its totals for the current and previous period. The entity `id` appears once at the item level; the metric buckets do not repeat it.", "properties": { "id": { "type": "string", "example": "64f0a1b2c3d4e5f60718293a" }, "current": { "type": "object", "example": { "total_posts": 42, "total_engagement": 8200, "total_impressions": 185000 } }, "previous": { "type": "object", "example": { "total_posts": 36, "total_engagement": 7100, "total_impressions": 165000 } }, "difference": { "type": "object", "example": { "total_posts": 6, "total_engagement": 1100, "total_impressions": 20000 } }, "percentage": { "type": "object", "example": { "total_posts": 16.7, "total_engagement": 15.5, "total_impressions": 12.1 } } }, "type": "object" }, "CampaignLabelInsightsPoint": { "description": "One day of totals for a single campaign or label.", "properties": { "date": { "type": "string", "format": "date", "example": "2026-01-14" }, "total_engagement": { "type": "integer", "example": 612 }, "total_impressions": { "type": "integer", "example": 15320 }, "total_posts": { "type": "integer", "example": 3 } }, "type": "object" }, "CampaignLabelPostRow": { "description": "One published post with its per-network metrics. A `null` metric means the network does not report it and must render as n/a β€” it is not the same as a reported `0`.", "properties": { "platform": { "type": "string", "example": "facebook" }, "account_id": { "type": "string", "example": "104857392012345" }, "post_id": { "type": "string", "example": "104857392012345_987654321098765" }, "caption": { "type": "string", "example": "Our spring launch is live" }, "thumbnail": { "type": "string", "example": "https://example.com/thumb.jpg" }, "permalink": { "type": "string", "example": "https://facebook.com/104857392012345/posts/987654321098765" }, "post_type": { "type": "string", "example": "photo" }, "published_at": { "type": "string", "format": "date-time", "example": "2026-01-14T09:32:00Z" }, "campaigns": { "description": "Every campaign the post belongs to, not only the filtered IDs.", "type": "array", "items": { "type": "string" }, "example": [ "64f0a1b2c3d4e5f60718293a" ] }, "labels": { "type": "array", "items": { "type": "string" }, "example": [] }, "metrics": { "type": "object", "example": { "engagement": 842, "views": null, "impressions": 15320, "reach": 11204, "link_clicks": 96, "video_views": 0, "likes": 700, "comments": 84, "shares": 58, "saves": null, "pin_clicks": null } } }, "type": "object" }, "CompetitorState": { "description": "Crawl state of the competitor, carried on every per-competitor row. `NotFound` means the competitor has no data yet - its metrics are absent, NOT zero. `Failed` means the last crawl errored, so the series may be stale or partial; it is not the same as `NotFound`. Only `Processed` means the figures are a complete measurement of the period.", "type": "string", "enum": [ "Processed", "NotFound", "Failed" ], "example": "Processed" }, "AdsAccount": { "description": "A connected ad account. currency is the account's own currency and is the unit of every monetary figure returned for it.", "properties": { "id": { "type": "string", "example": "act_1234567890" }, "name": { "type": "string", "example": "Acme Corp β€” Paid Social" }, "platform": { "type": "string", "enum": [ "meta_ads", "google_ads" ], "example": "meta_ads" }, "status": { "description": "Delivery status as the platform reports it. Meta returns an integer code, Google a string; neither is translated.", "example": 1 }, "currency": { "type": "string", "example": "USD" }, "image": { "type": "string", "example": "https://cdn.contentstudio.io/ad-account.png" }, "last_analytics_updated_at": { "type": "string", "example": "2026-08-17T04:12:09Z", "nullable": true } }, "type": "object" }, "AdsAccountsList": { "properties": { "status": { "type": "boolean", "example": true }, "total": { "type": "integer", "example": 3 }, "limit": { "type": "integer", "example": 15 }, "offset": { "type": "integer", "example": 0 }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/AdsAccount" } } }, "type": "object" }, "AdsForbidden": { "description": "Returned when the API key's owner may not read the requested ad account. The same response is returned whether the account belongs to another workspace, is not assigned to this member, or does not exist β€” the API does not confirm which ad account ids are real.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You do not have access to this ad account." }, "error_code": { "type": "string", "example": "AD_ACCOUNT_ACCESS_DENIED" } }, "type": "object" }, "AdsPagination": { "description": "Pagination envelope shared by every ads list endpoint. `total` is the number of rows matching the filters, not the number returned.", "properties": { "total": { "type": "integer", "example": 248 }, "limit": { "type": "integer", "example": 25 }, "offset": { "type": "integer", "example": 50 } }, "type": "object" }, "AdsTableRow": { "description": "One row of a Meta Ads campaign / ad set / ad table. `results` is counted according to the campaign's objective β€” see the metric glossary.", "properties": { "id": { "type": "string", "example": "23851234567890123" }, "name": { "type": "string", "example": "Spring Sale β€” Prospecting" }, "parent_id": { "type": "string", "example": "23851234567890000" }, "parent_name": { "type": "string", "example": "Spring Sale" }, "status": { "type": "string", "example": "ACTIVE" }, "objective": { "type": "string", "example": "OUTCOME_SALES" }, "results": { "type": "integer", "example": 182 }, "spend": { "type": "number", "format": "float", "example": 4210.55 }, "purchase_value": { "type": "number", "format": "float", "example": 18400 }, "roas": { "type": "number", "format": "float", "example": 4.37 }, "reach": { "type": "integer", "example": 98000 }, "impressions": { "type": "integer", "example": 185000 }, "frequency": { "type": "number", "format": "float", "example": 1.89 }, "clicks": { "type": "integer", "example": 3820 }, "cpm": { "type": "number", "format": "float", "example": 22.76 }, "cpc": { "type": "number", "format": "float", "example": 1.1 }, "ctr": { "type": "number", "format": "float", "example": 2.06 } }, "type": "object" }, "AdsAiInsightsGenerating": { "description": "Returned while an insight is still being generated. Subscribe to the Pusher channel and event, or simply repeat the request β€” generation is cached, so the finished insight comes back on a later call.", "properties": { "status": { "type": "string", "example": "generating" }, "phase": { "description": "Where generation has reached.", "type": "string", "example": "extracting_data" }, "request_id": { "type": "string", "example": "c6de5042f1c9aa5c" }, "channel": { "description": "Pusher channel carrying completion for this workspace.", "type": "string", "example": "ai-insights-65d837ac69574fceac020bc2" }, "event": { "type": "string", "example": "insights-c6de5042f1c9aa5c" }, "started_at": { "type": "string", "format": "date-time", "example": "2026-08-19T12:24:38Z" }, "elapsed_seconds": { "type": "integer", "example": 0 }, "platform": { "description": "Which insight the completion signal on that channel will be about. The event name is a digest of the cache key, so this is how a subscriber tells one completion from another.", "type": "string", "example": "meta_ads" }, "insight_type": { "description": "The insight type this generation is for.", "type": "string", "example": "aiInsightsDetailed" }, "detailed": { "description": "False for the summary, true for the full read-out.", "type": "boolean", "example": true }, "currency": { "type": "string", "example": "USD" }, "account_id": { "type": "string", "example": "1234567890" } }, "type": "object" }, "AdsAiInsightsResult": { "description": "A finished insight. Every field below the envelope is model-generated and returned verbatim from the analytics service, so treat each as optional and do not depend on any one being present. Text uses Markdown bold for emphasis, and monetary figures inside it are in the ad account's own currency. Both types return health_score and health_label; beyond those, aiInsightsSummary adds status_summary, summary_text and highlights, while aiInsightsDetailed adds status_headline, status_reason, status_tone, executive_summary, metrics, whats_happening, actions and suggested_prompts. Both platforms return the same field set for a given type.", "properties": { "status": { "type": "boolean", "example": true }, "currency": { "type": "string", "example": "USD" }, "account_id": { "type": "string", "example": "1234567890" }, "cached": { "description": "True when served from the 24-hour cache rather than generated for this request.", "type": "boolean", "example": true }, "generated_at": { "type": "string", "format": "date-time", "example": "2026-08-19T10:30:45Z" }, "analysis_window": { "type": "string", "example": "Jun 1, 2026 - Jun 30, 2026" }, "confidence": { "type": "string", "example": "High" }, "health_score": { "type": "integer", "example": 45 }, "health_label": { "type": "string", "example": "Needs attention" }, "status_summary": { "description": "aiInsightsSummary only.", "type": "string", "example": "Conversion slump" }, "summary_text": { "description": "aiInsightsSummary only.", "type": "string", "example": "Conversions fell by **80%** this month, pushing cost per conversion to **$49.65**." }, "highlights": { "description": "aiInsightsSummary only.", "type": "array", "items": { "type": "string" }, "example": [ "**Search | BRND** delivered **104** conversions at **$7.66** CPA." ] }, "status_headline": { "description": "aiInsightsDetailed only.", "type": "string", "example": "Conversions down, costs up" }, "status_reason": { "description": "aiInsightsDetailed only.", "type": "string", "example": "Spend held steady while conversions fell." }, "status_tone": { "description": "aiInsightsDetailed only.", "type": "string", "example": "negative" }, "executive_summary": { "description": "aiInsightsDetailed only.", "type": "array", "items": { "type": "string" } }, "metrics": { "description": "aiInsightsDetailed only β€” per-metric read-outs.", "type": "array", "items": { "type": "object" } }, "whats_happening": { "description": "aiInsightsDetailed only β€” an intro plus root-cause steps.", "type": "object" }, "actions": { "description": "aiInsightsDetailed only β€” recommended next steps.", "type": "array", "items": { "type": "object" } }, "suggested_prompts": { "description": "aiInsightsDetailed only β€” 3 follow-up questions the caller can put back to the AI.", "type": "array", "items": { "type": "string" }, "example": [ "How can I lower my CPA?", "Which ad sets should I pause?" ] }, "error": { "description": "Present when generation completed but failed; the envelope still reports status true.", "type": "string", "example": null, "nullable": true } }, "type": "object", "additionalProperties": true }, "AdsTrendPoint": { "properties": { "date": { "type": "string", "format": "date", "example": "2026-08-01" }, "value": { "type": "number", "format": "float", "example": 412.55 } }, "type": "object" }, "ApprovalWorkflowMember": { "properties": { "user_id": { "description": "Reusable OpenAPI schemas for the public-API approval-workflow and\ncascade-job responses.\n\nThe workflow object is returned by eight endpoints (list, create, show,\nupdate, duplicate, set-default, remove-default and the two 202 cascade\nshapes), so it is described once here and referenced via\n`@OA\\JsonContent(ref=\"#/components/schemas/\")`.", "type": "string", "example": "627a078300a7d866600e7d02" } }, "type": "object" }, "ApprovalWorkflowLevel": { "properties": { "level_number": { "type": "integer", "maximum": 5, "minimum": 1, "example": 1 }, "title": { "type": "string", "example": "Editors", "nullable": true }, "rule": { "description": "`anyone` clears the level on the first approval; `everyone` needs all members.", "type": "string", "enum": [ "anyone", "everyone" ], "example": "anyone" }, "members": { "description": "Empty makes the whole workflow a draft.", "type": "array", "items": { "$ref": "#/components/schemas/ApprovalWorkflowMember" } } }, "type": "object" }, "ApprovalWorkflow": { "properties": { "id": { "type": "string", "example": "66a1f2e4c8b9a1234567890d" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "66a1f2e4c8b9a1234567890d", "deprecated": true }, "name": { "type": "string", "example": "Marketing Approval" }, "is_draft": { "description": "A workflow with any unstaffed level is a draft; a draft cannot be attached to a post or made the default.", "type": "boolean", "example": false }, "is_default": { "description": "At most one workflow per workspace is the default.", "type": "boolean", "example": false }, "levels": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalWorkflowLevel" }, "maxItems": 5 } }, "type": "object" }, "ApprovalWorkflowInFlightLevel": { "properties": { "level_number": { "type": "integer", "example": 1 }, "count": { "type": "integer", "example": 2 } }, "type": "object" }, "ApprovalWorkflowDetail": { "description": "A workflow plus its runtime in-flight metrics. Only the single-workflow endpoint returns these two extra fields β€” each costs a count query and an aggregation, so the list endpoint omits them.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApprovalWorkflow" }, { "properties": { "in_flight_posts_count": { "description": "Posts currently pending or partially approved against this workflow. Non-zero means a delete needs `force=true`.", "type": "integer", "example": 3 }, "in_flight_level_breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalWorkflowInFlightLevel" } } }, "type": "object" } ] }, "ApprovalWorkflowList": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approval workflows retrieved successfully. Use a workflow's `id` as `approval_workflow.workflow_id` when creating or updating a post." }, "data": { "description": "Published (non-draft) workflows only.", "type": "array", "items": { "$ref": "#/components/schemas/ApprovalWorkflow" } } }, "type": "object" }, "ApprovalWorkflowCreated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approval workflow created successfully. Use the returned `id` as `approval_workflow.workflow_id` when creating or updating a post." }, "data": { "$ref": "#/components/schemas/ApprovalWorkflow" } }, "type": "object" }, "ApprovalWorkflowFetched": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approval workflows retrieved successfully." }, "data": { "$ref": "#/components/schemas/ApprovalWorkflowDetail" } }, "type": "object" }, "ApprovalWorkflowUpdated": { "description": "The definition is saved. Posts already in review keep the snapshot they were submitted under unless `confirmed=true` was passed.", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approval workflow updated successfully." }, "data": { "$ref": "#/components/schemas/ApprovalWorkflowDetail" } }, "type": "object" }, "ApprovalWorkflowUpdateCascading": { "description": "Saved, and the new levels are being re-applied to posts already in review. Poll `cascade_job_id` for progress.", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approval workflow updated; changes are being applied to posts already in review." }, "data": { "$ref": "#/components/schemas/ApprovalWorkflowDetail" }, "cascade_job_id": { "type": "string", "example": "66b0c1d2e3f4a5b6c7d8e9f0" } }, "type": "object" }, "ApprovalWorkflowDeleted": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approval workflow deleted successfully." }, "data": { "properties": { "was_default": { "description": "True means the workspace now has no default workflow until another is promoted.", "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" }, "ApprovalWorkflowDeleteCascading": { "description": "Deleted, and posts already in review are being cleaned up. Poll `cascade_job_id` for progress.", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approval workflow deleted; posts already in review are being updated." }, "was_default": { "type": "boolean", "example": false }, "cascade_job_id": { "type": "string", "example": "66b0c1d2e3f4a5b6c7d8e9f0" } }, "type": "object" }, "ApprovalWorkflowDuplicated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approval workflow duplicated successfully." }, "data": { "$ref": "#/components/schemas/ApprovalWorkflow" } }, "type": "object" }, "ApprovalWorkflowDefaultSet": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Approval workflow set as default." }, "data": { "$ref": "#/components/schemas/ApprovalWorkflow" } }, "type": "object" }, "ApprovalWorkflowDefaultRemoved": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Default removed." }, "data": { "$ref": "#/components/schemas/ApprovalWorkflow" } }, "type": "object" }, "ApprovalWorkflowUnauthorized": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" }, "ApprovalWorkflowForbidden": { "description": "Every approval-workflow route requires the `manage_workflow` permission. Owners, super-admins and admins have it automatically; approvers and collaborators need `allow_workflow_management`.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You do not have permission to perform this action." } }, "type": "object" }, "ApprovalWorkflowNotFound": { "description": "Also returned for a workflow that was deleted β€” a deleted id behaves as if it never existed.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Approval workflow not found in this workspace." }, "error_code": { "type": "string", "example": "APPROVAL_WORKFLOW_NOT_FOUND" } }, "type": "object" }, "ApprovalWorkflowValidationError": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed: Level numbers must be unique." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "levels": [ "Level numbers must be unique." ], "levels.0.members": [ "Members must be unique within a level." ], "levels.members": [ "One or more members are not workspace team members." ] } } }, "type": "object" }, "ApprovalWorkflowForceDeleteRequired": { "description": "Nothing was deleted. Re-send with `force=true` to delete anyway, which queues a cleanup cascade over the affected posts.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This approval workflow has posts in review. Pass force=true to delete it anyway." }, "error_code": { "type": "string", "example": "REQUIRES_FORCE_DELETE" }, "context": { "properties": { "in_flight_posts_count": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" }, "ApprovalWorkflowDraftDefaultRejected": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "A draft approval workflow cannot be set as default." }, "error_code": { "type": "string", "example": "CANNOT_SET_DRAFT_AS_DEFAULT" } }, "type": "object" }, "ApprovalWorkflowWriteFailed": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to update approval workflow." }, "error_code": { "type": "string", "enum": [ "APPROVAL_WORKFLOW_CREATE_FAILED", "APPROVAL_WORKFLOW_UPDATE_FAILED", "APPROVAL_WORKFLOW_DELETE_FAILED", "APPROVAL_WORKFLOW_DUPLICATE_FAILED" ], "example": "APPROVAL_WORKFLOW_UPDATE_FAILED" } }, "type": "object" }, "ApprovalWorkflowRateLimited": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" }, "CascadeJob": { "properties": { "id": { "type": "string", "example": "66b0c1d2e3f4a5b6c7d8e9f0" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "66b0c1d2e3f4a5b6c7d8e9f0", "deprecated": true }, "type": { "type": "string", "enum": [ "workflow_changes", "workflow_deletion", "member_removal" ], "example": "workflow_changes" }, "status": { "description": "Terminal states are `completed`, `partially_failed` (finished, with per-post problems in `failures`) and `failed`.", "type": "string", "enum": [ "queued", "processing", "completed", "partially_failed", "failed" ], "example": "completed" }, "total_count": { "type": "integer", "example": 12 }, "processed_count": { "type": "integer", "example": 12 }, "failed_count": { "type": "integer", "example": 0 }, "failures": { "type": "array", "items": { "type": "object" }, "example": [] }, "started_at": { "type": "string", "example": "2026-09-08T10:15:00+00:00", "nullable": true }, "completed_at": { "type": "string", "example": "2026-09-08T10:15:07+00:00", "nullable": true } }, "type": "object" }, "CascadeJobFetched": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Cascade job retrieved successfully." }, "data": { "$ref": "#/components/schemas/CascadeJob" } }, "type": "object" }, "CascadeJobNotFound": { "description": "Also returned for a job that belongs to a different workspace, so an id cannot be probed across workspaces.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Cascade job not found in this workspace." }, "error_code": { "type": "string", "example": "CASCADE_JOB_NOT_FOUND" } }, "type": "object" }, "BrandColor": { "required": [ "hex", "role" ], "properties": { "hex": { "description": "Reusable OpenAPI schemas for the public-API brand knowledge endpoints.\n\nThe brand object is returned by read, create and update, so it is described\nonce here. It is a versioned public shape (`schema_version`), not the stored\ndocument: section `id`s, legacy v1 fields and extracted source `content`\nnever appear.", "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "example": "#2F7BF6" }, "role": { "description": "At most one each of `brand`, `background` and `text`; any further colors are `accent`.", "type": "string", "enum": [ "brand", "background", "text", "accent" ], "example": "brand" } }, "type": "object" }, "BrandStyle": { "description": "The Brand Style tab: logo, colors and fonts.", "properties": { "logo": { "description": "Public URL of the logo, or an empty string.", "type": "string", "format": "url", "example": "https://example.com/logo.png" }, "colors": { "type": "array", "items": { "$ref": "#/components/schemas/BrandColor" }, "maxItems": 6 }, "title_font": { "type": "string", "example": "Poppins" }, "body_font": { "type": "string", "example": "Inter" }, "visual_identity_description": { "type": "string", "maxLength": 10000, "example": "Clean, airy layouts with bold blue accents." } }, "type": "object" }, "BrandProfile": { "description": "The Brand Profile tab: who the business is and how it is positioned. Each list entry is at most 200 characters.", "properties": { "business_name": { "type": "string", "maxLength": 10000, "example": "Acme Coffee" }, "core_identity": { "type": "string", "maxLength": 10000, "example": "A specialty roaster sourcing directly from farmers." }, "market_positioning": { "type": "string", "maxLength": 10000, "example": "Premium beans at a fair price, delivered fresh." }, "competitors": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "example": [ "Blue Bottle" ] }, "competitive_advantages": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "example": [ "Roasted to order" ] }, "primary_customer_segments": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "example": [ "Home baristas" ] }, "primary_value_drivers": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "example": [ "Freshness" ] } }, "type": "object" }, "BrandVoice": { "description": "The Brand Voice tab. `tone`, `emotion`, `character` and `language` are free text, as in the product. Values brand analysis most commonly produces β€” tone: Professional, Confident, Approachable, Helpful, Warm, Authoritative, Enthusiastic, Friendly; emotion: Trust, Empowerment, Confidence, Excitement, Reliability, Inspiration; language: Clear, Straightforward, Conversational, Accessible, Concise, Simple, Technical. `character` takes personality descriptors in the same style. Each list entry is at most 200 characters.", "properties": { "purpose": { "type": "string", "maxLength": 10000, "example": "Help people brew better coffee at home." }, "audience": { "type": "string", "maxLength": 10000, "example": "Coffee enthusiasts aged 25-45" }, "tone": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "example": [ "Professional", "Warm" ] }, "emotion": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "example": [ "Trust" ] }, "character": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "example": [ "Knowledgeable" ] }, "language": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "example": [ "Clear", "Conversational" ] }, "voice_description": { "type": "string", "maxLength": 10000, "example": "Warm and knowledgeable, never snobbish." } }, "type": "object" }, "BrandSourceMaterial": { "description": "Summary of a source material. Its extracted text is not returned.", "properties": { "id": { "type": "string", "example": "0b6c1f0e-8c1e-4d4c-9c43-6f1f3b0f9a11" }, "name": { "type": "string", "example": "acme.coffee" }, "type": { "type": "string", "enum": [ "website", "document", "text", "social" ], "example": "website" }, "url": { "description": "The website for a website source, the file for a document; null for text and social sources.", "type": "string", "example": "https://acme.coffee", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "synced", "unreachable" ], "example": "synced" }, "last_synced_at": { "type": "string", "example": "2026-10-01 09:00:00", "nullable": true }, "added_at": { "type": "string", "example": "2026-10-01 08:59:12", "nullable": true } }, "type": "object" }, "Brand": { "description": "The workspace brand. A workspace without one returns `is_set_up: false`, empty sections and null timestamps.", "properties": { "schema_version": { "description": "Version of this public shape. Changes to storage never change it.", "type": "integer", "example": 1 }, "is_set_up": { "description": "The brand carries content AI generation would use.", "type": "boolean", "example": true }, "brand_enabled": { "description": "Whether the brand is applied to AI generation.", "type": "boolean", "example": true }, "brand_style": { "$ref": "#/components/schemas/BrandStyle" }, "brand_profile": { "$ref": "#/components/schemas/BrandProfile" }, "brand_voice": { "$ref": "#/components/schemas/BrandVoice" }, "source_materials": { "type": "array", "items": { "$ref": "#/components/schemas/BrandSourceMaterial" } }, "brand_assets": { "description": "Media library items flagged as brand assets; same shape as the media endpoints.", "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "example": "2026-10-01T08:59:12+00:00", "nullable": true }, "updated_at": { "description": "When the brand was last changed.", "type": "string", "example": "2026-10-06T10:15:00+00:00", "nullable": true } }, "type": "object" }, "BrandCreate": { "description": "The sources of the app's **Build My Brand Knowledge** and **Add Source Material** screens. At least one is required.", "properties": { "website_url": { "description": "The brand's website; it is scraped and analysed.", "type": "string", "format": "url", "example": "https://acme.coffee" }, "text": { "description": "Anything about the brand, in your own words.", "type": "string", "maxLength": 10000, "example": "We roast specialty coffee in small batches and ship within 48 hours." }, "files": { "description": "Brand documents β€” PDF, DOCX, TXT or Markdown β€” as public `https` URLs. The analysis service downloads them.", "type": "array", "items": { "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "example": "https://acme.coffee/brand-guidelines.pdf" }, "name": { "description": "Display name of the source; defaults to the file name.", "type": "string", "maxLength": 255, "example": "Brand guidelines", "nullable": true } }, "type": "object" }, "maxItems": 50 }, "social_accounts": { "description": "Account `id`s from `GET /accounts` whose recent posts are analysed. Supported: Facebook, X (Twitter), Instagram, LinkedIn, Pinterest, Telegram, YouTube, TikTok, Tumblr, Google Business Profile, Bluesky.", "type": "array", "items": { "type": "string" }, "example": [ "1329910333529595" ] } }, "type": "object" }, "BrandWrite": { "description": "Body of PATCH. Every section and every field is optional. Only the fields sent change; a list field sent replaces that list. Unknown keys are rejected.", "properties": { "brand_style": { "properties": { "logo": { "description": "Public `http(s)` URL, or empty/null to clear. A ContentStudio storage URL is accepted only for the current logo or a file in this workspace's media library (e.g. one uploaded with the media endpoints).", "type": "string", "nullable": true }, "colors": { "type": "array", "items": { "$ref": "#/components/schemas/BrandColor" }, "maxItems": 6 }, "title_font": { "type": "string", "nullable": true }, "body_font": { "type": "string", "nullable": true }, "visual_identity_description": { "type": "string", "maxLength": 10000, "nullable": true } }, "type": "object" }, "brand_profile": { "$ref": "#/components/schemas/BrandProfile" }, "brand_voice": { "$ref": "#/components/schemas/BrandVoice" }, "brand_enabled": { "description": "Apply the brand to AI generation.", "type": "boolean", "example": true } }, "type": "object" }, "BrandResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Brand retrieved successfully." }, "data": { "$ref": "#/components/schemas/Brand" } }, "type": "object" }, "BrandCreatedResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Brand created successfully." }, "data": { "$ref": "#/components/schemas/Brand" } }, "type": "object" }, "BrandUpdatedResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Brand updated successfully." }, "data": { "$ref": "#/components/schemas/Brand" } }, "type": "object" }, "BrandSyncedResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Brand re-synced from its sources." }, "data": { "$ref": "#/components/schemas/Brand" } }, "type": "object" }, "BrandDeleted": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Brand deleted successfully." }, "data": { "properties": { "deleted": { "type": "boolean", "example": true }, "brand_assets": { "description": "Brand asset media items removed.", "type": "integer", "example": 12 }, "source_materials": { "type": "integer", "example": 3 }, "logo": { "description": "Whether a logo was removed.", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "BrandSourcesAdded": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Source materials added successfully." }, "data": { "properties": { "added": { "description": "The sources created, in the order processed. `status` is `synced` once analysed into the brand, or `unreachable` when the analysis could not use the source (it is kept).", "type": "array", "items": { "$ref": "#/components/schemas/BrandSourceMaterial" } }, "brand": { "$ref": "#/components/schemas/Brand" } }, "type": "object" } }, "type": "object" }, "BrandSourceDeleted": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Source material deleted successfully." }, "data": { "properties": { "deleted": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "0b6c1f0e-8c1e-4d4c-9c43-6f1f3b0f9a11" }, "auto_reply_rules_affected": { "description": "Inbox auto-reply rules that used this document as guidance and no longer do.", "type": "array", "items": { "type": "string" }, "example": [ "Shipping questions" ] } }, "type": "object" } }, "type": "object" }, "BrandSectionResponse": { "description": "One of `brand_style`, `brand_profile` or `brand_voice`, depending on the section requested.", "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Brand retrieved successfully." }, "data": { "properties": { "schema_version": { "type": "integer", "example": 1 }, "is_set_up": { "type": "boolean", "example": true }, "brand_voice": { "$ref": "#/components/schemas/BrandVoice" }, "updated_at": { "type": "string", "example": "2026-10-06T10:15:00+00:00", "nullable": true } }, "type": "object" } }, "type": "object" }, "BrandPostSettings": { "description": "Post generation defaults, as in the AI Content Library's post settings. In a PATCH every field is optional.", "properties": { "social_platform": { "description": "Required before anything can be saved, as in the app.", "type": "string", "enum": [ "instagram", "facebook", "twitter", "telegram", "tiktok", "gmb", "threads", "bluesky", "linkedin", "tumblr" ], "example": "instagram", "nullable": true }, "language": { "type": "string", "enum": [ "English", "Spanish", "French", "Portuguese", "German", "Italian", "Dutch", "Turkish", "Indonesian", "Tagalog", "Swedish", "Danish", "Norwegian", "Romanian", "Polish", "Finnish", "Hungarian", "Greek", "Czech", "Malay", "Vietnamese", "Chinese (Simplified)", "Chinese (Traditional)" ], "example": "English" }, "post_type": { "type": "string", "enum": [ "image", "text", "text_image" ], "example": "image" }, "no_of_posts": { "type": "integer", "maximum": 10, "minimum": 1, "example": 10 }, "caption_length": { "type": "integer", "maximum": 200, "minimum": 20, "example": 40 }, "emoji_usage": { "type": "string", "enum": [ "none", "low", "medium", "high" ], "example": "medium" }, "hashtag_usage": { "type": "string", "enum": [ "none", "low", "medium", "high" ], "example": "medium" }, "aspect_ratio": { "type": "string", "enum": [ "8:1", "4:1", "21:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16", "1:4", "1:8" ], "example": "1:1" }, "image_style": { "description": "The app's image styles; `none` for no style.", "type": "string", "enum": [ "none", "abstract", "oil-painting", "neon-punk", "app-icon", "black-white", "bokeh", "cartoon", "cinematic", "cyberpunk", "digital-watercolor", "film-noir", "film-poster", "flat-design", "futuristic", "grunge", "highly-detailed", "isometric", "minimalistic", "photorealistic", "pixel-art", "polaroid", "pop-art", "retro-80s", "steampunk", "sticker", "super-realistic", "surrealism", "tattoo", "unreal-engine", "vaporwave" ], "example": "none" } }, "type": "object" }, "BrandPostSettingsResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Post generation settings retrieved successfully." }, "data": { "$ref": "#/components/schemas/BrandPostSettings" } }, "type": "object" }, "BrandPostSettingsUpdatedResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Post generation settings updated successfully." }, "data": { "$ref": "#/components/schemas/BrandPostSettings" } }, "type": "object" }, "BrandUnauthorized": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" }, "BrandForbidden": { "description": "The API key's user is not a member of this workspace (`WORKSPACE_ACCESS_DENIED`, or `WORKSPACE_INVITATION_PENDING` before an invitation is accepted), or the workspace is locked (`WORKSPACE_LOCKED`).", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." }, "error_code": { "type": "string", "enum": [ "WORKSPACE_ACCESS_DENIED", "WORKSPACE_INVITATION_PENDING", "WORKSPACE_LOCKED" ], "example": "WORKSPACE_ACCESS_DENIED" } }, "type": "object" }, "BrandValidationError": { "description": "Every invalid field and broken limit, keyed by field path.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The brand style.colors field must not have more than 6 items." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "brand_style.colors": [ "The brand style.colors field must not have more than 6 items." ], "brand_voice.tone.1": [ "The brand_voice.tone.1 field must not be greater than 200 characters." ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "BrandRateLimited": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" }, "BrandError": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This workspace already has a brand. Use PATCH to update it." }, "error_code": { "type": "string", "enum": [ "BRAND_ALREADY_EXISTS", "BRAND_NOT_FOUND", "BRAND_INSUFFICIENT_CONTENT", "BRAND_ANALYSIS_FAILED", "BRAND_SOURCE_NOT_FOUND", "BRAND_SOURCE_ADD_FAILED" ], "example": "BRAND_ALREADY_EXISTS" } }, "type": "object" }, "ContentCategoryAccount": { "description": "A social account attached to the category, resolved from its stored id.", "properties": { "id": { "description": "Reusable OpenAPI schemas for the public-API content-category responses.\n\nReferenced from the controller via\n`@OA\\JsonContent(ref=\"#/components/schemas/\")` so the category object\nis described once instead of being restated on create, update and delete β€”\nand so none of them can drift into an empty `data: {}` placeholder.", "type": "string", "example": "106939092115395" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "106939092115395", "deprecated": true }, "platform": { "type": "string", "enum": [ "facebook", "twitter", "linkedin", "pinterest", "gmb", "instagram", "youtube", "tiktok", "threads", "bluesky", "telegram", "tumblr" ], "example": "facebook" }, "name": { "type": "string", "example": "My Facebook Page" } }, "type": "object" }, "ContentCategory": { "description": "A workspace-local content category. Same field set the list endpoint returns, so a mutation response and a list item are interchangeable.", "properties": { "id": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "66a1f2e4c8b9a1234567890b", "deprecated": true }, "name": { "type": "string", "example": "Product Launch" }, "color": { "type": "string", "enum": [ "color_1", "color_2", "color_3", "color_4", "color_5", "color_6", "color_7", "color_8", "color_9", "color_10", "color_11", "color_12", "color_13", "color_14", "color_15", "color_16", "color_17", "color_18", "color_19", "color_20" ], "example": "color_3" }, "color_code": { "description": "Hex value the `color` token maps to.", "type": "string", "example": "#ff6462", "nullable": true }, "state": { "type": "string", "example": "active", "nullable": true }, "category_state": { "description": "Always `local` for categories managed through this endpoint.", "type": "string", "example": "local" }, "slots_count": { "description": "Weekly posting slots configured on this category.", "type": "integer", "example": 0 }, "posts_count": { "description": "Posts assigned to this category.", "type": "integer", "example": 0 }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/ContentCategoryAccount" } } }, "type": "object" }, "ContentCategoryCreated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Content category created successfully. Use the returned `id` as `content_category_id` when scheduling a post assigned to this category." }, "data": { "$ref": "#/components/schemas/ContentCategory" } }, "type": "object" }, "ContentCategoryUpdated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Content category updated successfully." }, "data": { "$ref": "#/components/schemas/ContentCategory" } }, "type": "object" }, "ContentCategoryDeleted": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Content category deleted successfully." }, "data": { "description": "Always empty on delete.", "type": "array", "items": {}, "example": [] } }, "type": "object" }, "ContentCategoryFetched": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Content category retrieved successfully." }, "data": { "description": "The category, plus its full weekly schedule so no second call is needed.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ContentCategory" }, { "properties": { "slots": { "type": "array", "items": { "$ref": "#/components/schemas/ContentCategorySlot" } } }, "type": "object" } ] } }, "type": "object" }, "ContentCategoryShuffled": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Your posts have been shuffled." }, "data": { "properties": { "shuffled_posts_count": { "description": "Upcoming posts whose times were reassigned among themselves.", "type": "integer", "example": 7 } }, "type": "object" } }, "type": "object" }, "ContentCategoryNextSlot": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Next available slot resolved." }, "data": { "properties": { "next_slot": { "description": "When a post queued now would publish. Null when the category has no upcoming slot.", "type": "string", "example": "2026-09-15 09:30:00", "nullable": true }, "timezone": { "description": "The workspace timezone `next_slot` is expressed in.", "type": "string", "example": "Pacific/Niue" }, "scheduled": { "description": "True when `post_id` was supplied and the answer is that post's own scheduled time rather than the next free slot.", "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" }, "ContentCategoryUnauthorized": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" }, "ContentCategoryAccessDenied": { "description": "Returned when the caller is a workspace member but has no per-category access to this category β€” the same filtering the list endpoint applies.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You do not have access to this content category." }, "error_code": { "type": "string", "example": "CONTENT_CATEGORY_ACCESS_DENIED" } }, "type": "object" }, "ContentCategoryNotFound": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Content category not found in this workspace." }, "error_code": { "type": "string", "example": "CONTENT_CATEGORY_NOT_FOUND" } }, "type": "object" }, "ContentCategoryValidationError": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed: The name field is required." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field is required." ], "color": [ "The color must be one of color_1 to color_20." ], "accounts": [ "One or more account IDs are not valid for this workspace." ] } } }, "type": "object" }, "ContentCategoryWriteRejected": { "description": "A write the endpoint refuses: the target is a global category copy, an account id does not resolve in this workspace, or the underlying write failed.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This is a global content category and cannot be changed through this endpoint." }, "error_code": { "type": "string", "enum": [ "CONTENT_CATEGORY_IS_GLOBAL", "CONTENT_CATEGORY_INVALID_ACCOUNT", "CONTENT_CATEGORY_CREATE_FAILED", "CONTENT_CATEGORY_UPDATE_FAILED", "CONTENT_CATEGORY_DELETE_FAILED" ], "example": "CONTENT_CATEGORY_IS_GLOBAL" } }, "type": "object" }, "ContentCategoryIsGlobal": { "description": "The target is a global category copy. Global categories are managed on their own surface; this endpoint only handles workspace-local categories.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This is a global content category and cannot be changed through this endpoint." }, "error_code": { "type": "string", "example": "CONTENT_CATEGORY_IS_GLOBAL" } }, "type": "object" }, "ContentCategoryRateLimited": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" }, "ContentCategorySlot": { "description": "One weekly posting slot. Times are 12-hour: `hour` 0-11 plus an AM/PM `period`.", "properties": { "id": { "description": "Reusable OpenAPI schemas for the content-category slot responses.\n\nThe slot object is returned by list, create and update, so it is described\nonce here and referenced via\n`@OA\\JsonContent(ref=\"#/components/schemas/\")`. Error envelopes shared\nwith the parent resource (unauthorized, access denied, category not found,\nvalidation, rate limited) come from ContentCategoryApiSchemas.", "type": "string", "example": "66c3d1a2b4e5f6789012345a" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "66c3d1a2b4e5f6789012345a", "deprecated": true }, "category_id": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" }, "day": { "type": "string", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "example": "monday" }, "weekday_sorting": { "description": "The day's index, Sunday = 0 β€” the order the scheduler sorts by.", "type": "integer", "example": 1 }, "hour": { "description": "Stored on a 12-hour clock; 0 with period AM is midnight, 0 with PM is noon.", "type": "integer", "maximum": 11, "minimum": 0, "example": 9 }, "minute": { "type": "integer", "maximum": 59, "minimum": 0, "example": 30 }, "period": { "type": "string", "enum": [ "AM", "PM" ], "example": "AM" } }, "type": "object" }, "ContentCategorySlotList": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Content category slots retrieved successfully." }, "data": { "description": "Ordered by period then hour.", "type": "array", "items": { "$ref": "#/components/schemas/ContentCategorySlot" } } }, "type": "object" }, "ContentCategorySlotCreated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Posting slot added successfully." }, "data": { "$ref": "#/components/schemas/ContentCategorySlot" } }, "type": "object" }, "ContentCategorySlotUpdated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Posting slot updated successfully." }, "data": { "$ref": "#/components/schemas/ContentCategorySlot" } }, "type": "object" }, "ContentCategorySlotDeleted": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Posting slot removed successfully." }, "data": { "description": "Always empty on delete.", "type": "array", "items": {}, "example": [] } }, "type": "object" }, "ContentCategorySlotValidationError": { "description": "Slot validation failure. The fields are always day/hour/minute/period β€” a slot request accepts nothing else, and `category_id`/`workspace_id` are path segments.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed: The selected day is invalid." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "day": [ "The selected day is invalid." ], "hour": [ "The hour field must be between 0 and 12." ], "minute": [ "The minute field must be between 0 and 59." ], "period": [ "The selected period is invalid." ] } } }, "type": "object" }, "ContentCategorySlotNotFound": { "description": "Also returned when the slot exists but belongs to another category or workspace, so a slot id cannot be probed across categories.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "No slot exists with your provided id." }, "error_code": { "type": "string", "example": "CONTENT_CATEGORY_SLOT_NOT_FOUND" } }, "type": "object" }, "ContentCategorySlotRejected": { "description": "A slot write the endpoint refuses: the same day and time already has a slot on this category, the category is a global copy, or the underlying write failed.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This category already has a posting slot at that day and time." }, "error_code": { "type": "string", "enum": [ "CONTENT_CATEGORY_SLOT_DUPLICATE", "CONTENT_CATEGORY_IS_GLOBAL", "CONTENT_CATEGORY_SLOT_CREATE_FAILED", "CONTENT_CATEGORY_SLOT_UPDATE_FAILED", "CONTENT_CATEGORY_SLOT_DELETE_FAILED" ], "example": "CONTENT_CATEGORY_SLOT_DUPLICATE" } }, "type": "object" }, "UsageLimitEntry": { "description": "One metered entitlement. `note` is always present and carries every qualitative fact about the allowance in words β€” whether it is unlimited, absent from the plan, denominated in bytes, and whether it resets monthly or is a running total. `api_credits` is a single pool covering both direct API calls and webhook deliveries; its note breaks the two apart.", "properties": { "key": { "type": "string", "enum": [ "workspaces", "social_accounts", "team_members", "x_posting_credits", "listening_topics", "listening_mentions", "ai_text_credits", "ai_image_credits", "ai_video_credits", "video_clip_credits", "ai_auto_reply_credits", "automations", "media_storage", "api_credits" ], "example": "social_accounts" }, "label": { "description": "Localised display name, matching the wording used in the product.", "type": "string", "example": "Social Accounts" }, "used": { "description": "Bytes for `media_storage`, a count for everything else β€” `note` says which.", "type": "integer", "example": 13 }, "limit": { "description": "Null when the entitlement is unlimited, in which case `note` says so.", "type": "integer", "example": 16, "nullable": true }, "remaining": { "description": "Null whenever `limit` is. Never negative: usage can exceed a limit after a downgrade, in which case this is 0.", "type": "integer", "example": 3, "nullable": true }, "scope": { "description": "What `used` counts. `workspace` is this workspace alone; `account` is every workspace the account owner has. Account-wide: workspaces, social_accounts, team_members, listening_topics, automations, media_storage. The credit counters are per-workspace.", "type": "string", "enum": [ "workspace", "account" ], "example": "account" }, "is_unlimited": { "description": "True when the plan grants this without a ceiling; `limit` and `remaining` are then null.", "type": "boolean", "example": false }, "is_on_plan": { "description": "False when the plan does not carry this at all β€” distinct from a fully consumed allowance, which `limit: null` alone cannot express.", "type": "boolean", "example": true }, "unit": { "description": "`bytes` for media_storage, `count` for everything else.", "type": "string", "enum": [ "count", "bytes" ], "example": "count" }, "period": { "description": "`monthly` for credits that clear with the billing cycle, `lifetime` for running totals.", "type": "string", "enum": [ "monthly", "lifetime" ], "example": "lifetime" }, "resets_at": { "description": "ISO 8601 instant the counter next clears. Null when `period` is `lifetime`.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "note": { "description": "The state of this allowance in words.", "type": "string", "example": "Resets on the 1st of each month; next reset 2026-10-01T00:00:00+00:00." } }, "type": "object" }, "WorkspaceLimitsResponse": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Limits and usage retrieved successfully." }, "data": { "properties": { "plan": { "description": "Which plan produced these entitlements.", "properties": { "slug": { "type": "string", "example": "agency-annual" }, "name": { "type": "string", "example": "Business & Agency - Medium (Annually)" }, "is_annually": { "description": "True only when the plan bills yearly; false for monthly and quarterly.", "type": "boolean", "example": true }, "billing_cycle": { "description": "How often the plan bills.", "type": "string", "enum": [ "monthly", "quarterly", "annually" ], "example": "annually" } }, "type": "object" }, "limits": { "type": "array", "items": { "$ref": "#/components/schemas/UsageLimitEntry" } }, "usage_reset": { "description": "Periodic counters (AI credits, API calls, mentions, X posting) are cleared together on the 1st of each month, UTC, for every workspace β€” not on a per-customer billing anniversary.", "properties": { "last_reset_at": { "description": "When the counters were last cleared. Null on a workspace the job has not yet touched, which is why `next_reset_at` is derived from the schedule rather than from this.", "type": "string", "format": "date-time", "example": "2026-09-01T00:05:12+00:00", "nullable": true }, "next_reset_at": { "description": "When they next clear: 00:00 UTC on the 1st of next month.", "type": "string", "format": "date-time", "example": "2026-10-01T00:00:00+00:00" }, "note": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "LimitsUnauthorized": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" }, "LimitsForbidden": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied." } }, "type": "object" }, "LimitsWorkspaceNotFound": { "description": "Raised by the workspace resolver before the endpoint runs, for an id that does not exist or is malformed.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found." } }, "type": "object" }, "LimitsRateLimited": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" }, "MediaBadRequest": { "properties": { "status": { "description": "Reusable OpenAPI schemas for the public-API media error responses.\n\nReferenced from the media controllers via\n`@OA\\JsonContent(ref=\"#/components/schemas/\")` so the same envelope is\nnot repeated on ~60 error responses.\n\nThe shapes differ by who answers: 401 and the workspace-access 403 come from\nApiKeyMiddleware / PermissionMiddleware, which emit `{status, message}` with\nno `error_code`. Controller failures go through `localizedFlatError`, which\nalways adds one.", "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed." }, "errors": { "type": "object", "example": { "per_page": [ "The per page field must not be greater than 100." ] } } }, "type": "object" }, "MediaUnauthorized": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" }, "MediaForbidden": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." } }, "type": "object" }, "MediaNotFound": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Media not found in this workspace." }, "error_code": { "type": "string", "example": "MEDIA_NOT_FOUND" } }, "type": "object" }, "MediaValidationError": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "media_ids": [ "The media ids field is required." ] } } }, "type": "object" }, "MediaRateLimited": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" }, "MediaServerError": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Storage usage is temporarily unavailable. Please try again." }, "error_code": { "type": "string", "example": "MEDIA_STORAGE_UNAVAILABLE" } }, "type": "object" }, "PostObject": { "properties": { "id": { "type": "string", "example": "61e006a89be9dd0cd07ec692" }, "workspace_id": { "type": "string", "example": "610a1e660cb41530ca40d372" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published", "failed", "rejected", "under_review", "missed_review", "partially_failed", "in_progress", "notification_sent", "notification_declined" ], "example": "scheduled" }, "post_url": { "description": "Deep link to the post in the planner list view. Null when no whitelabel/workspace slug is resolvable.", "type": "string", "example": "https://app.contentstudio.io/my-workspace/publisher/planner/list-view?plan_ids=61e006a89be9dd0cd07ec692", "nullable": true }, "post_type": { "description": "The post_type this post was created with. NULL for posts created before the API began recording it β€” the per-platform fields it fans out to are not invertible, so an unknown value is reported as null rather than guessed. Send it back on PUT or the post reverts to a plain feed post.", "type": "string", "example": "reel", "nullable": true }, "post_video_title": { "description": "Video title, at the same top level the store request takes it, so a GET can be re-posted unchanged.", "type": "string", "example": "Launch cut", "nullable": true }, "instagram_options": { "description": "Empty object when no Instagram account is selected.", "properties": { "collaborators": { "type": "array", "items": { "type": "string" }, "example": [ "brandpartner" ] } }, "type": "object" }, "common": { "properties": { "content": { "properties": { "text": { "type": "string", "example": "Check out our latest product launch! " }, "media": { "properties": { "images": { "type": "array", "items": { "properties": { "url": { "type": "string", "example": "https://example.com/image1.jpg" } }, "type": "object" } }, "video": { "properties": { "url": { "type": "string", "example": "https://example.com/video.mp4" }, "thumbnail": { "type": "string", "example": "https://example.com/thumb.jpg", "nullable": true }, "duration": { "type": "string", "example": "00:34", "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "platform_overrides": { "description": "Per-platform content overrides, keyed by platform name. NOTE: this field is an OBJECT only when overrides exist; a post with no overrides (i.e. the composer used one shared box) returns an EMPTY ARRAY `[]`, not `{}`. Decode it as a loose/optional map, and treat `[]` as `no overrides`. Only the platforms that actually carry their own copy appear. Note `media` is always present on an override, as `{images: [], video: null}` when that platform overrides text only.", "properties": { "facebook": { "description": "Shape is the same for every platform key (twitter, instagram, linkedin, …).", "properties": { "content": { "properties": { "text": { "type": "string", "example": "Separate copy for Facebook πŸ‘" }, "media": { "properties": { "images": { "type": "array", "items": { "properties": { "url": { "type": "string", "example": "https://example.com/fb-image.jpg" } }, "type": "object" } }, "video": { "properties": { "url": { "type": "string", "example": "https://example.com/video.mp4" }, "thumbnail": { "type": "string", "nullable": true }, "duration": { "type": "string", "example": "00:34", "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "accounts": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "350830594784444" }, "platform": { "type": "string", "enum": [ "facebook", "twitter", "linkedin", "pinterest", "instagram", "gmb", "youtube", "tiktok", "tumblr", "threads", "bluesky", "telegram" ], "example": "facebook" }, "name": { "type": "string", "example": "My Business Page" }, "username": { "type": "string", "example": "@mybusiness" }, "posting_status": { "description": "Result of the publishing attempt for this account. Present only once a posting record exists.", "type": "string", "enum": [ "success", "error" ], "example": "success", "nullable": true }, "post_link": { "description": "Live URL of the published post. Present when posting_status is success.", "type": "string", "example": "https://facebook.com/350830594784444/posts/123", "nullable": true }, "error_message": { "description": "Failure reason. Present when posting_status is error.", "type": "string", "nullable": true }, "deleted": { "description": "True when the published post was later deleted on the platform.", "type": "boolean", "example": false }, "deleted_message": { "type": "string", "nullable": true } }, "type": "object" } }, "scheduling": { "properties": { "publish_type": { "type": "string", "enum": [ "draft", "scheduled", "published", "failed", "rejected", "under_review", "missed_review", "partial", "in_progress", "notification_sent", "notification_declined" ], "example": "scheduled" }, "execute_time": { "description": "Resolved execution time of the post. Null when no execution time is set.", "type": "string", "format": "date-time", "example": "2025-07-25T15:30:00Z", "nullable": true }, "repeat": { "description": "This post's repeat settings and its place in a repeat series. Always present and always populated: `type`/`times`/`gap` carry the stored defaults (Day/1/3) on a post that does not repeat, mirroring how the composer always sends them with the switch off. `is_parent`/`is_child` are what tell you whether a series exists. There is deliberately NO `enabled` key here β€” that is request-only β€” so a client can read a post and send `scheduling` straight back without creating children by accident. Children are independent posts: editing or deleting a parent does not change them.", "properties": { "is_parent": { "description": "This post's schedule generated the children.", "type": "boolean", "example": true }, "is_child": { "description": "This post was generated by another post's repeat schedule.", "type": "boolean", "example": false }, "parent_id": { "description": "Id of the post this child came from. Null on a parent.", "type": "string", "example": "6aa3984024cbeb43a0004a92", "nullable": true }, "type": { "description": "Stored interval unit. `Day` on a post that does not repeat.", "type": "string", "enum": [ "Day", "Week", "Month" ], "example": "Day" }, "times": { "description": "Stored child count. 1 on a post that does not repeat.", "type": "integer", "example": 2 }, "gap": { "description": "Stored interval, in units of `type`. 3 on a post that does not repeat.", "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-05T10:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-01-05T10:30:00Z" }, "created_by": { "type": "string", "example": "John Doe", "nullable": true }, "content_category_id": { "description": "Empty string when the post is not tied to a content category.", "type": "string", "example": "66a1f2e4c8b9a1234567890d" }, "hide_client": { "type": "boolean", "example": false }, "labels": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "66a1f2e4c8b9a1234567890b" }, "name": { "type": "string", "example": "Marketing" }, "color": { "type": "string", "example": "color_1" } }, "type": "object" } }, "campaign": { "description": "Campaign/folder information. Empty object {} when no campaign assigned.", "properties": { "id": { "type": "string", "example": "66a1f2e4c8b9a1234567890c" }, "name": { "type": "string", "example": "Summer Campaign" }, "color": { "type": "string", "example": "color_9" } }, "type": "object" }, "first_comment": { "description": "First comment payload. Empty object {} when not configured.", "properties": { "message": { "type": "string", "example": "Don't forget to check our website!" }, "accounts": { "type": "array", "items": { "type": "string", "example": "66a1f2e4c8b9a1234567890e" } } }, "type": "object" }, "gmb_options": { "description": "Google My Business options. Empty object {} when no GMB account is targeted.", "properties": { "topic_type": { "type": "string", "example": "STANDARD" }, "start_date": { "type": "string", "nullable": true }, "end_date": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "action_type": { "type": "string", "nullable": true }, "cta_link": { "type": "string", "nullable": true } }, "type": "object" }, "youtube_options": { "description": "YouTube options. Empty object {} when no YouTube account is targeted. Note: category is returned as the stored YouTube category ID, not the name accepted on the store endpoint.", "properties": { "title": { "type": "string", "nullable": true }, "privacy_status": { "type": "string", "example": "public" }, "category": { "type": "string", "example": "22", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "license": { "type": "string", "nullable": true }, "made_for_kids": { "type": "boolean" } }, "type": "object" }, "tiktok_options": { "description": "TikTok options. Empty object {} when no TikTok account is targeted.", "properties": { "privacy_level": { "type": "string", "example": "PUBLIC_TO_EVERYONE" }, "disable_comment": { "type": "boolean" }, "disable_duet": { "type": "boolean" }, "disable_stitch": { "type": "boolean" }, "auto_add_music": { "type": "boolean" }, "brand_content_toggle": { "type": "boolean" }, "is_aigc": { "type": "boolean" } }, "type": "object" }, "pinterest_options": { "description": "Pinterest title and destination link. Empty object {} when no Pinterest account is targeted.", "properties": { "title": { "type": "string", "nullable": true }, "link": { "type": "string", "format": "uri", "nullable": true } }, "type": "object" }, "twitter_options": { "description": "Twitter/X thread options. Empty object {} when no Twitter account is targeted or threads are disabled.", "properties": { "has_threaded_tweets": { "type": "boolean", "example": true }, "threaded_tweets": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Part 1 of the thread" }, "media": { "type": "array", "items": { "type": "string", "example": "https://example.com/media.jpg" } } }, "type": "object" } } }, "type": "object" }, "threads_options": { "description": "Threads multi-thread options. Empty object {} when no Threads account is targeted or multi-threads are disabled.", "properties": { "has_multi_threads": { "type": "boolean", "example": true }, "multi_threads": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Part 1 of the thread" }, "media": { "type": "array", "items": { "type": "string", "example": "https://example.com/media.jpg" } } }, "type": "object" } } }, "type": "object" }, "facebook_options": { "description": "Facebook options. Empty object {} when no Facebook account is targeted.", "properties": { "facebook_background_id": { "description": "Empty string when no text-post background preset is selected.", "type": "string", "example": "" }, "carousel": { "description": "Carousel payload reshaped to the store-request format. NOTE: this field is an OBJECT only for an actual carousel; a non-carousel post returns an EMPTY ARRAY `[]`, not `{}`. Treat `[]` as `not a carousel`.", "properties": { "is_carousel_post": { "type": "boolean", "example": true }, "cards": { "type": "array", "items": { "properties": { "image": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "description": { "type": "string" }, "link": { "type": "string", "format": "uri" } }, "type": "object" } }, "accounts": { "type": "array", "items": { "type": "string" } }, "call_to_action": { "type": "string", "example": "NO_BUTTON" }, "end_card": { "type": "boolean" }, "end_card_url": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" }, "linkedin_options": { "description": "LinkedIn options. Empty object {} when no LinkedIn account is targeted or no options are set.", "properties": { "title": { "type": "string", "example": "Q3 Product Highlights" }, "is_carousel": { "type": "boolean", "example": true }, "accounts": { "type": "array", "items": { "type": "string", "example": "105256406" } }, "post_type": { "type": "string", "example": "poll" }, "poll": { "description": "Present only for poll posts.", "properties": { "question": { "type": "string", "example": "Which framework do you prefer?" }, "options": { "type": "array", "items": { "type": "string", "example": "Vue" } }, "duration": { "type": "string", "example": "SEVEN_DAYS" } }, "type": "object" } }, "type": "object" }, "approval": { "description": "Legacy single-level approval. Empty object {} when no legacy approval is set.", "properties": { "status": { "type": "string", "enum": [ "pending_approval", "completed_approval", "rejected_approval" ], "example": "pending_approval", "nullable": true }, "approve_option": { "type": "string", "enum": [ "anyone", "all" ], "example": "anyone", "nullable": true }, "notes": { "type": "string", "example": "Please review before publishing", "nullable": true }, "approvers": { "type": "array", "items": { "properties": { "user_id": { "type": "string", "example": "66a1f2e4c8b9a1234567890d", "nullable": true }, "name": { "type": "string", "example": "Jane Smith", "nullable": true }, "email": { "type": "string", "example": "jane@example.com", "nullable": true }, "is_external": { "type": "boolean", "example": false }, "status": { "type": "string", "enum": [ "pending", "approve", "reject" ], "example": "pending" }, "last_action_time": { "type": "string", "format": "date-time", "example": "2026-01-10T15:30:00Z", "nullable": true }, "last_action_note": { "type": "string", "example": "Looks good, approved!", "nullable": true } }, "type": "object" } } }, "type": "object" }, "approval_workflow": { "description": "Multi-level approval workflow snapshot. Empty object {} when the post uses no workflow.", "properties": { "workflow_id": { "type": "string", "example": "66a1f2e4c8b9a1234567890d" }, "workflow_name": { "type": "string", "example": "Marketing Approval", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "partially_approved", "fully_approved", "rejected" ], "example": "pending", "nullable": true }, "current_level": { "type": "integer", "example": 1 }, "total_levels": { "type": "integer", "example": 2 }, "notes": { "type": "string", "nullable": true }, "submitted_at": { "type": "string", "format": "date-time", "example": "2026-01-10T15:30:00Z", "nullable": true }, "levels": { "type": "array", "items": { "properties": { "level_number": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Editors", "nullable": true }, "rule": { "type": "string", "enum": [ "anyone", "everyone" ], "example": "anyone", "nullable": true }, "members": { "type": "array", "items": { "properties": { "user_id": { "type": "string", "example": "627a078300a7d866600e7d02" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "no_action_needed" ], "example": "pending" }, "actioned_at": { "type": "string", "format": "date-time", "nullable": true }, "comment": { "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" } } }, "type": "object" }, "external_actions": { "description": "External action participants. Each item only exposes the external user's name and email.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "h2", "nullable": true }, "email": { "type": "string", "example": "hello@yopmail.com", "nullable": true }, "action": { "type": "string", "example": "approve", "nullable": true } }, "type": "object" } }, "external_comments": { "description": "External comments with minimal comment metadata.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "h2", "nullable": true }, "email": { "type": "string", "example": "hello@yopmail.com", "nullable": true }, "comment": { "type": "string", "example": "Looks good", "nullable": true }, "reaction": { "type": "array", "items": { "type": "object" } }, "is_resolved": { "type": "boolean", "example": false } }, "type": "object" } } }, "type": "object" }, "ShareLink": { "description": "A public, tokenized link to a planner calendar or post list. Never carries the link password or its external-approval tokens.", "properties": { "id": { "description": "Reusable OpenAPI schemas for the public-API share-link responses.\n\nThe link object is returned by list, create, update and delete-adjacent\nresponses, so it is described once and referenced via\n`@OA\\JsonContent(ref=\"#/components/schemas/\")`.\n\nNote what is deliberately ABSENT from ShareLink: `password` and\n`approval_tokens`. Both exist on the model and on ShareLinkData, and the\ninternal endpoints return them β€” documenting them here would be documenting\na leak.", "type": "string", "example": "66a1f2e4c8b9a1234567890b" }, "_id": { "description": "Deprecated alias for `id` β€” will be removed once clients migrate.", "type": "string", "example": "66a1f2e4c8b9a1234567890b", "deprecated": true }, "name": { "type": "string", "example": "Q1 Client Recap" }, "link_id": { "description": "The public token in the URL: a slug of the name plus a unique suffix.", "type": "string", "example": "q1-client-recap-a1b2c3" }, "url": { "description": "Built on the workspace's own domain, so white-labelled workspaces get their own host.", "type": "string", "example": "https://app.contentstudio.io/share/planner/q1-client-recap-a1b2c3", "nullable": true }, "scope": { "description": "`selection` shares an explicit post list; `future`/`all` share a calendar window. Null if the stored value is not one the UI produces.", "type": "string", "enum": [ "selection", "future", "all" ], "example": "selection", "nullable": true }, "view": { "description": "Presentation hint. Null for an unrecognised stored value.", "type": "string", "enum": [ "list", "calendar", "compact_list" ], "example": "list", "nullable": true }, "is_password_protected": { "type": "boolean", "example": false }, "is_disabled": { "description": "A disabled link stops resolving without being deleted.", "type": "boolean", "example": false }, "show_notes": { "type": "boolean", "example": false }, "is_single_post": { "type": "boolean", "example": false }, "allow_external_comments": { "type": "boolean", "example": true }, "allow_external_approval_actions": { "type": "boolean", "example": false }, "approval_flow": { "description": "Whether the external-approval-by-email flow is enabled.", "type": "boolean", "example": false }, "approval_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [] }, "approval_option": { "type": "string", "enum": [ "anyone", "everyone" ], "example": null, "nullable": true }, "approval_status": { "type": "string", "example": null, "nullable": true }, "outstanding_invitations_count": { "description": "External approvers with a live, un-actioned invitation.", "type": "integer", "example": 0 }, "created_at": { "type": "string", "example": "2026-09-02T10:00:00+00:00", "nullable": true }, "updated_at": { "type": "string", "example": "2026-09-02T10:00:00+00:00", "nullable": true } }, "type": "object" }, "ShareLinkList": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Shareable links retrieved successfully." }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 3 }, "last_page": { "type": "integer", "example": 1 }, "from": { "type": "integer", "example": 1, "nullable": true }, "to": { "type": "integer", "example": 3, "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShareLink" } } }, "type": "object" }, "ShareLinkCreated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Shareable link created successfully. Share the returned `url` with recipients, or use `id` to update or delete this link." }, "data": { "$ref": "#/components/schemas/ShareLink" } }, "type": "object" }, "ShareLinkUpdated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Shareable link updated successfully." }, "data": { "$ref": "#/components/schemas/ShareLink" } }, "type": "object" }, "ShareLinkDeleted": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Shareable link deleted successfully." }, "data": { "properties": { "outstanding_invitations_count": { "description": "External approvers who were mid-review when the link was deleted. Non-zero means their email links have stopped working.", "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" }, "ShareLinkInvitationsSent": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Invitations sent to 1 recipient(s)." }, "data": { "properties": { "recipients": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" }, "ShareLinkFetched": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Share link retrieved successfully." }, "data": { "$ref": "#/components/schemas/ShareLink" } }, "type": "object" }, "ShareLinkActivityEntry": { "description": "One thing a recipient did through the link.", "properties": { "type": { "type": "string", "enum": [ "comment", "action" ], "example": "comment" }, "post_id": { "type": "string", "example": "66a1f2e4c8b9a1234567890c" }, "name": { "type": "string", "example": "Jane Client", "nullable": true }, "email": { "type": "string", "example": "jane@client.example", "nullable": true }, "comment": { "description": "The comment text, or the note left alongside an approval action.", "type": "string", "example": "Looks good, ship it", "nullable": true }, "action": { "description": "Present only on an approval action.", "type": "string", "enum": [ "approve", "reject" ], "example": null, "nullable": true }, "created_at": { "type": "string", "example": "2026-09-10 08:15:00", "nullable": true } }, "type": "object" }, "ShareLinkActivity": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Share link activity retrieved successfully." }, "total": { "type": "integer", "example": 3 }, "data": { "description": "Newest first.", "type": "array", "items": { "$ref": "#/components/schemas/ShareLinkActivityEntry" } } }, "type": "object" }, "ShareLinkUnauthorized": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" }, "ShareLinkForbidden": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Access denied to this workspace" } }, "type": "object" }, "ShareLinkNotFound": { "description": "Also returned when the link exists but belongs to another workspace, so an id cannot be probed across tenants.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Shareable link not found in this workspace." }, "error_code": { "type": "string", "example": "SHARE_LINK_NOT_FOUND" } }, "type": "object" }, "ShareLinkValidationError": { "description": "Field names are always share-link fields. `name` allows letters, digits and spaces only because it is slugified into the public URL.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed: The name field format is invalid." }, "error_code": { "type": "string", "example": "VALIDATION_ERROR" }, "errors": { "type": "object", "example": { "name": [ "The name field format is invalid." ], "scope": [ "Sharing future or all content requires the calendar view." ], "calendar_date": [ "A date range is required when sharing future or all content." ], "plans": [ "One or more post IDs are not valid for this workspace." ] } } }, "type": "object" }, "ShareLinkWriteFailed": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Failed to update shareable link." }, "error_code": { "type": "string", "enum": [ "SHARE_LINK_CREATE_FAILED", "SHARE_LINK_UPDATE_FAILED", "SHARE_LINK_DELETE_FAILED", "SHARE_LINK_INVITE_FAILED" ], "example": "SHARE_LINK_UPDATE_FAILED" } }, "type": "object" }, "ShareLinkRateLimited": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" }, "WebhookObject": { "description": "A webhook endpoint. The signing secret is never included β€” `has_secret` says whether one is set. It is returned once, by create and by rotate-secret.", "properties": { "id": { "type": "string", "example": "66f1c2a9e4b0a1b2c3d4e5f6" }, "name": { "description": "Defaults to the URL's host.", "type": "string", "example": "Order sync", "nullable": true }, "url": { "type": "string", "format": "uri", "example": "https://hooks.example.com/contentstudio" }, "event_types": { "type": "array", "items": { "type": "string" }, "example": [ "post.published", "post.failed" ] }, "status": { "description": "`disabled_by_system` means ContentStudio paused it after 15 consecutive failed deliveries and emailed the owner; set `status: enabled` to resume.", "type": "string", "enum": [ "enabled", "disabled", "disabled_by_system" ], "example": "enabled" }, "has_secret": { "type": "boolean", "example": true }, "custom_headers": { "description": "Extra headers sent with every delivery. They cannot override `content-type`, `user-agent`, `host`, `webhook-id`, `webhook-timestamp` or `x-contentstudio-signature`.", "type": "object", "example": { "X-Tenant": "acme" }, "additionalProperties": { "type": "string" } }, "last_delivery_at": { "type": "string", "format": "date-time", "example": "2026-10-06T09:12:44+00:00", "nullable": true }, "last_delivery_status": { "type": "string", "enum": [ "delivered", "failed", "skipped_out_of_credits" ], "example": "delivered", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-01T08:00:00+00:00", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-10-06T09:12:44+00:00", "nullable": true } }, "type": "object" }, "WebhookEventType": { "properties": { "value": { "description": "The value to subscribe with and the `type` of the delivered envelope.", "type": "string", "example": "post.published" }, "label": { "type": "string", "example": "Post published" }, "group": { "type": "string", "enum": [ "posts", "inbox" ], "example": "posts" }, "description": { "type": "string", "example": "A post finishes publishing to its accounts." }, "payload_schema": { "description": "The schema in this document that describes the envelope's `data` for this event.", "type": "string", "enum": [ "WebhookPostEventData", "WebhookInboxEventData", "WebhookAutomationEventData" ], "example": "WebhookPostEventData" } }, "type": "object" }, "WebhookEnvelope": { "description": "The JSON body of every delivery, POSTed to the webhook URL with `Content-Type: application/json`. Deliveries follow the Standard Webhooks specification (standardwebhooks.com) and carry three headers: `webhook-id` (equal to `id`, stable across retries β€” use it to de-duplicate), `webhook-timestamp` (Unix seconds) and, when the webhook has a secret, `x-contentstudio-signature`.\n *\n * **Verifying a delivery.** Build the signed content as `{webhook-id}.{webhook-timestamp}.{raw request body}` β€” the raw bytes, before any JSON parsing. Base64-decode the part of the secret after `whsec_` to get the key, compute HMAC-SHA256 over the signed content and base64-encode the digest. The header holds one or more space-separated `v1,` entries; accept the delivery if any entry equals your computed value (compare in constant time), and reject it if `webhook-timestamp` is more than 5 minutes from now. While a rotation's grace period is open the header carries two entries, one per secret. Any Standard Webhooks library (for example `standardwebhooks` or Svix's) verifies it unchanged: pass the `x-contentstudio-signature` value as its `webhook-signature` header.\n *\n * Respond with any 2xx within 30 seconds. Timeouts, 408, 429 and 5xx are retried with exponential backoff for up to 7 attempts; other 4xx are not retried. Each successful delivery uses one API credit from the account's monthly pool (see `GET /api/v1/workspaces/{workspace_id}/limits`, key `api_credits`).", "properties": { "id": { "description": "Event ID, equal to the `webhook-id` header.", "type": "string", "example": "01J9Z3W4QK8X6M2N5P7R9T1V3B" }, "type": { "type": "string", "example": "post.published" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-10-06T09:12:44+00:00" }, "data": { "description": "Shape depends on `type`; see the event type's `payload_schema`.", "type": "object" } }, "type": "object" }, "WebhookPostEventData": { "description": "`data` for every `post.*` event. `post` is the same representation `GET /api/v1/workspaces/{workspace_id}/posts` returns. Fields beyond `workspace_id`, `event_status` and `post` appear only on the events noted.", "properties": { "workspace_id": { "type": "string", "example": "610a1e660cb41530ca40d372" }, "event_status": { "type": "string", "enum": [ "scheduled", "published", "partially_failed", "failed", "in_review", "approved", "rejected", "comment_added" ], "example": "published" }, "counts": { "description": "post.published and post.failed only.", "properties": { "published": { "type": "integer", "example": 3 }, "failed": { "type": "integer", "example": 0 }, "notification_sent": { "type": "integer", "example": 0 } }, "type": "object" }, "approval": { "description": "post.inreview, post.approved and post.rejected only.", "properties": { "type": { "type": "string", "enum": [ "workflow", "legacy" ], "example": "workflow" }, "status": { "type": "string", "example": "pending", "nullable": true } }, "type": "object", "nullable": true }, "actor_user_id": { "description": "post.approved and post.rejected only.", "type": "string", "example": "5f8d0d55b54764421b7156c3", "nullable": true }, "note": { "description": "post.approved and post.rejected only.", "type": "string", "example": "Looks good", "nullable": true }, "comment": { "description": "post.comment only.", "properties": { "id": { "type": "string", "example": "66f1c2a9e4b0a1b2c3d4e5f7" }, "plan_id": { "type": "string", "example": "66f1c2a9e4b0a1b2c3d4e5f8" }, "user_id": { "type": "string", "example": "5f8d0d55b54764421b7156c3" }, "comment": { "type": "string", "example": "Can we swap the image?" }, "is_note": { "type": "boolean", "example": false }, "mentioned_user": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-06T09:12:44+00:00", "nullable": true } }, "type": "object" }, "post": { "$ref": "#/components/schemas/PostObject" } }, "type": "object" }, "WebhookInboxEventData": { "description": "`data` for every `inbox.*` event. `account` identifies the connected social account. Received events carry the item (`conversation` + `message`, `post` + `comment`, or `review` + `reviewer`); triage events (`inbox.assigned`, `inbox.completed`, `inbox.archived`, `inbox.note.created`) carry `item` and `actor`.", "properties": { "workspace_id": { "type": "string", "example": "610a1e660cb41530ca40d372" }, "account": { "properties": { "id": { "type": "string", "example": "17841400000000000" }, "platform": { "type": "string", "example": "instagram" } }, "type": "object" }, "conversation": { "description": "inbox.message.received only.", "type": "object" }, "message": { "description": "inbox.message.received only.", "properties": { "id": { "type": "string", "example": "m_1" }, "text": { "type": "string", "example": "Do you ship to Canada?", "nullable": true }, "created_time": { "type": "string", "example": "2026-10-06T09:12:44+00:00", "nullable": true } }, "type": "object" }, "post": { "description": "inbox.comment.received only.", "type": "object" }, "comment": { "description": "inbox.comment.received only.", "type": "object" }, "review": { "description": "inbox.review.received only.", "type": "object" }, "reviewer": { "description": "inbox.review.received only.", "type": "object" }, "item": { "description": "Triage events only.", "properties": { "id": { "type": "string", "example": "c_1" }, "type": { "type": "string", "example": "conversation" } }, "type": "object" }, "actor": { "description": "Triage events only β€” the team member who acted.", "type": "object" } }, "type": "object" }, "WebhookAutomationEventData": { "description": "`data` for `automation.bulk.completed`. Fetch the created posts from `GET /api/v1/workspaces/{workspace_id}/automations/bulk/{csv_id}/rows`.", "properties": { "workspace_id": { "type": "string", "example": "610a1e660cb41530ca40d372" }, "event_status": { "type": "string", "enum": [ "completed" ], "example": "completed" }, "bulk": { "properties": { "csv_id": { "type": "string", "example": "66f1c2a9e4b0a1b2c3d4e5f9" }, "total": { "type": "integer", "example": 40 }, "processed": { "type": "integer", "example": 40 }, "has_valid_posts": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "WebhookCreateRequest": { "required": [ "url", "event_types" ], "properties": { "url": { "description": "Must be HTTPS and publicly reachable.", "type": "string", "format": "uri", "maxLength": 2048, "example": "https://hooks.example.com/contentstudio" }, "event_types": { "description": "Values from `GET /api/v1/workspaces/{workspace_id}/webhooks/event-types`.", "type": "array", "items": { "type": "string" }, "minItems": 1, "example": [ "post.published", "post.failed" ] }, "name": { "type": "string", "maxLength": 120, "example": "Order sync", "nullable": true }, "secret": { "description": "Optional `whsec_` secret of your own. Omit it and one is generated. Either way it is returned in the response once.", "type": "string", "example": null, "nullable": true }, "custom_headers": { "type": "object", "example": { "X-Tenant": "acme" }, "nullable": true, "additionalProperties": { "type": "string" } } }, "type": "object" }, "WebhookUpdateRequest": { "description": "Send only the fields to change.", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "example": "https://hooks.example.com/contentstudio-v2" }, "event_types": { "type": "array", "items": { "type": "string" }, "minItems": 1, "example": [ "post.published" ] }, "name": { "type": "string", "maxLength": 120, "example": "Order sync", "nullable": true }, "custom_headers": { "type": "object", "example": { "X-Tenant": "acme" }, "additionalProperties": { "type": "string" } }, "status": { "description": "`disabled` pauses deliveries; `enabled` resumes them, including after ContentStudio disabled the webhook.", "type": "string", "enum": [ "enabled", "disabled" ], "example": "disabled" } }, "type": "object" }, "WebhookEventTypeList": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Event types retrieved successfully" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } } }, "type": "object" }, "WebhookList": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhooks retrieved successfully" }, "used": { "description": "Webhooks the user has, active and paused.", "type": "integer", "example": 2 }, "limit": { "description": "Maximum webhooks per user.", "type": "integer", "example": 5 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookObject" } } }, "type": "object" }, "WebhookCreated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook created successfully" }, "data": { "description": "The webhook, plus its signing secret.", "allOf": [ { "$ref": "#/components/schemas/WebhookObject" }, { "properties": { "secret": { "description": "The signing secret. Shown only in this response.", "type": "string", "example": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" } }, "type": "object" } ] } }, "type": "object" }, "WebhookFetched": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhooks retrieved successfully" }, "data": { "$ref": "#/components/schemas/WebhookObject" } }, "type": "object" }, "WebhookUpdated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook updated successfully" }, "data": { "$ref": "#/components/schemas/WebhookObject" } }, "type": "object" }, "WebhookDeleted": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook deleted successfully" }, "data": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, "WebhookSecretRotated": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Signing secret regenerated. Copy it now β€” it will not be shown again. Deliveries are signed with both the new and the previous secret until 2026-10-07T09:12:44+00:00." }, "data": { "description": "The webhook, plus its new signing secret and when the previous one stops signing.", "allOf": [ { "$ref": "#/components/schemas/WebhookObject" }, { "properties": { "secret": { "description": "The new signing secret. Shown only in this response.", "type": "string", "example": "whsec_Lq3nT1fUaV7cXw0yZ2bD4eG6hJ8kM0pR" }, "previous_secret_expires_at": { "description": "Until then deliveries are signed with both secrets. Null when the webhook had no secret before.", "type": "string", "format": "date-time", "example": "2026-10-07T09:12:44+00:00", "nullable": true } }, "type": "object" } ] } }, "type": "object" }, "WebhookDelivery": { "description": "One event sent to the webhook, shown by its latest attempt.", "properties": { "event_id": { "description": "Equal to the delivery's `webhook-id` header and envelope `id`.", "type": "string", "example": "01J9Z3W4QK8X6M2N5P7R9T1V3B" }, "event_type": { "type": "string", "example": "post.published" }, "outcome": { "type": "string", "enum": [ "delivered", "failed", "retrying", "skipped_out_of_credits" ], "example": "failed" }, "response_status": { "description": "HTTP status your endpoint answered with; null when it could not be reached.", "type": "integer", "example": 503, "nullable": true }, "duration_ms": { "type": "integer", "example": 184 }, "is_test": { "type": "boolean", "example": false }, "created_at": { "description": "When the latest attempt was made, UTC.", "type": "string", "example": "2026-10-06 09:12:44.512", "nullable": true } }, "type": "object" }, "WebhookDeliveryList": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Deliveries retrieved successfully" }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 42 }, "last_page": { "type": "integer", "example": 2 }, "from": { "type": "integer", "example": 1, "nullable": true }, "to": { "type": "integer", "example": 25, "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "type": "object" }, "WebhookUnauthorized": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid or revoked API key" } }, "type": "object" }, "WebhookForbidden": { "description": "Returned when the caller is not a member of the workspace in the path (`WORKSPACE_ACCESS_DENIED`, or `WORKSPACE_INVITATION_PENDING` before an invitation is accepted), the workspace is locked (`WORKSPACE_LOCKED`), or it has no API credits to spend.", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "API credit limit exceeded. Please contact support@contentstudio.io." }, "error_code": { "type": "string", "enum": [ "WORKSPACE_ACCESS_DENIED", "WORKSPACE_INVITATION_PENDING", "WORKSPACE_LOCKED", "API_ACCESS_NOT_ALLOWED", "API_CREDIT_LIMIT_EXCEEDED" ], "example": "API_CREDIT_LIMIT_EXCEEDED" } }, "type": "object" }, "WebhookWorkspaceNotFound": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Workspace not found. The workspace ID \"610a1e660cb41530ca40d372\" does not exist." } }, "type": "object" }, "WebhookNotFound": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Webhook not found" }, "error_code": { "type": "string", "example": "WEBHOOK_NOT_FOUND" } }, "type": "object" }, "WebhookUnprocessable": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This URL points to a private or internal address. Use a publicly reachable HTTPS endpoint." }, "error_code": { "type": "string", "enum": [ "VALIDATION_ERROR", "WEBHOOK_LIMIT_REACHED", "WEBHOOK_URL_NOT_ALLOWED", "WEBHOOK_PREFLIGHT_FAILED" ], "example": "WEBHOOK_URL_NOT_ALLOWED" }, "errors": { "description": "Per-field messages; `VALIDATION_ERROR` only.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "WebhookRequestFailed": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong." }, "error_code": { "type": "string", "example": "WEBHOOK_REQUEST_FAILED" } }, "type": "object" }, "WebhookRateLimited": { "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too Many Requests. Rate limit exceeded." }, "error_code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "retry_after": { "type": "integer", "example": 60 } }, "type": "object" }, "WorkspaceAccessDenied": { "description": "Returned when a workspace access check refuses the request.\n\n- `WORKSPACE_ACCESS_DENIED`: the API key's user is not a member of the workspace\n- `WORKSPACE_INVITATION_PENDING`: the user was invited but has not joined the workspace yet\n- `WORKSPACE_LOCKED`: the workspace owner's account is not active or past due (e.g. trial finished, cancelled)\n- `PERMISSION_DENIED`: the user's role or team permissions do not allow this action\n- `ACCOUNT_ACCESS_DENIED`: the request names a social or ad account the user is not assigned to\n- `FEATURE_NOT_IN_PLAN`: the workspace owner's plan does not include this feature", "properties": { "status": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You are not allowed to perform this action." }, "error_code": { "type": "string", "enum": [ "WORKSPACE_ACCESS_DENIED", "WORKSPACE_INVITATION_PENDING", "WORKSPACE_LOCKED", "PERMISSION_DENIED", "ACCOUNT_ACCESS_DENIED", "FEATURE_NOT_IN_PLAN" ], "example": "PERMISSION_DENIED" } }, "type": "object" } }, "parameters": { "AnalyticsWorkspaceId": { "name": "workspace_id", "in": "path", "description": "Workspace Id", "required": true, "schema": { "type": "string", "example": "610a1e660cb41530ca40d372" } }, "AnalyticsPlatformId": { "name": "platform_id", "in": "query", "description": "Platform Account ID", "required": true, "schema": { "type": "string" } }, "AnalyticsStartDate": { "name": "start_date", "in": "query", "description": "Start of the date range (YYYY-MM-DD)", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, "AnalyticsEndDate": { "name": "end_date", "in": "query", "description": "End of the date range (YYYY-MM-DD)", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-01-31" } }, "AnalyticsDateRange": { "name": "date", "in": "query", "description": "Alternative date range in 'YYYY-MM-DD - YYYY-MM-DD' format (overrides start_date/end_date)", "required": false, "schema": { "type": "string", "example": "2024-01-01 - 2024-01-31" } }, "AnalyticsTimezone": { "name": "timezone", "in": "query", "description": "IANA timezone name", "required": false, "schema": { "type": "string", "default": "UTC", "example": "America/New_York" } }, "AnalyticsLimit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, "AnalyticsOffset": { "name": "offset", "in": "query", "description": "Number of records to skip for pagination", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, "AnalyticsOrderDirection": { "name": "order_direction", "in": "query", "description": "Sort direction for the endpoint's sort field (`order_by`, or `sort_order` on TikTok).", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, "AnalyticsCompetitorReportId": { "name": "competitor_report_id", "in": "query", "description": "The saved competitor report to read. Returned by the competitor report endpoints.", "required": true, "schema": { "type": "string", "example": "66f0a1e660cb41530ca40d37" } }, "AnalyticsHashtag": { "name": "hashtag", "in": "query", "description": "The hashtag to break down, without the leading '#'.", "required": true, "schema": { "type": "string", "example": "marketing" } }, "AnalyticsMediaProductType": { "name": "media_product_type", "in": "query", "description": "Instagram surface filter, alongside media_type. Comma-separated.", "required": false, "schema": { "type": "string", "example": "FEED,REELS" } }, "MetaAdsAccountId": { "name": "account_id", "in": "query", "description": "The Meta ad account identifier, as returned by the ad-accounts endpoint. Both the `act_`-prefixed and the bare form are accepted.", "required": true, "schema": { "type": "string", "example": "act_1234567890" } }, "GoogleAdsAccountId": { "name": "account_id", "in": "query", "description": "The Google Ads customer id, as returned by the ad-accounts endpoint. Both the hyphenated and the bare form are accepted.", "required": true, "schema": { "type": "string", "example": "1234567890" } }, "AdsCampaignId": { "name": "campaign_id", "in": "query", "description": "Restrict results to a single campaign.", "required": false, "schema": { "type": "string", "example": "23851234567890123" } }, "AdsOrderBy": { "name": "order_by", "in": "query", "description": "Metric to sort by. The accepted set is documented per endpoint.", "required": false, "schema": { "type": "string", "example": "spend" } }, "AdsOrderDir": { "name": "order_dir", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, "AdsSearch": { "name": "search", "in": "query", "description": "Case-insensitive substring match on the row's name.", "required": false, "schema": { "type": "string" } }, "AdsStatus": { "name": "status", "in": "query", "description": "Filter by delivery status. Accepted values vary per account and are returned in each list response under `available_statuses`.", "required": false, "schema": { "type": "string", "example": "ACTIVE" } } }, "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "description": "API Key authentication using X-API-Key header: 'X-API-Key: cs_your_api_key_here'", "name": "X-API-Key", "in": "header" } } }, "tags": [ { "name": "🎠 AI Carousels", "description": "Generate an ordered, branded carousel (slides plus one caption), edit it, and schedule it with the posts API" }, { "name": "🎨 AI Images", "description": "Synchronous AI image generation and image tools" }, { "name": "🎬 AI Videos", "description": "Async AI video generation, tools, and job status" }, { "name": "πŸ“Š Analytics: Bluesky", "description": "Retrieve Bluesky account analytics β€” current follower totals, authored-post performance (likes, reposts, replies, quotes), publishing behaviour, top posts, single post detail, posting cadence and hashtag usage. Reach, impressions and demographics are not available from the AT Protocol; call the capabilities endpoint for the authoritative list.", "x-displayName": "Bluesky" }, { "name": "πŸ—‚οΈ Campaigns & Labels", "description": "Cross-network performance for posts grouped by campaign or label β€” summary KPIs, a per-post table, and top posts per network." }, { "name": "πŸ“˜ Facebook", "description": "Retrieve Facebook page analytics β€” summary KPIs, audience growth, top posts, demographics, video and Reels insights, and AI-generated highlights." }, { "name": "πŸ“ Google My Business", "description": "Retrieve Google My Business location analytics β€” summary KPIs, impressions, actions, search keywords, top posts, publishing behaviour, reviews, media activity, and AI-generated highlights." }, { "name": "πŸ” Google Ads", "description": "Retrieve Google Ads performance β€” spend, conversions, campaign / ad group / ad tables, keywords, search terms, Shopping, conversion reporting, demographics, and AI-generated highlights." }, { "name": "πŸ“Έ Instagram", "description": "Retrieve Instagram account analytics β€” summary KPIs, audience growth, top posts, hashtags, stories and Reels performance, demographics, and AI-generated highlights." }, { "name": "πŸ’Ό LinkedIn", "description": "Retrieve LinkedIn page analytics β€” summary KPIs, audience growth, page views, publishing behaviour, top posts, hashtags, follower demographics, and AI-generated highlights." }, { "name": "♾️ Meta Ads", "description": "Retrieve Meta (Facebook & Instagram) ads performance β€” spend, results by objective, campaign / ad set / ad tables, placement and demographic breakdowns, and AI-generated highlights." }, { "name": "πŸ“Œ Pinterest", "description": "Retrieve Pinterest account analytics β€” summary KPIs, follower and impression trends, engagement, pin posting activity, top and single pin detail, pin performance over time, and AI-generated highlights." }, { "name": "πŸ“Š Analytics: Threads", "description": "Retrieve Threads account analytics β€” follower totals and demographics, profile views and link clicks, post performance (likes, replies, reposts, quotes), publishing behaviour, top posts, single post detail, posting cadence, hashtags and topic tags. Reach and impressions are not available from the Threads API; call the capabilities endpoint for the authoritative list.", "x-displayName": "Threads" }, { "name": "🎡 TikTok", "description": "Retrieve TikTok account analytics β€” summary KPIs, follower trend, publishing behaviour, engagement trend, top posts, single post lookup, sorted post tables, and AI-generated highlights." }, { "name": "βœ–οΈ X/Twitter", "description": "Retrieve Twitter/X account analytics β€” summary KPIs, engagement & impression trends, follower growth, top tweets, least-performing tweets, single tweet details, and API credits usage." }, { "name": "▢️ YouTube", "description": "Retrieve YouTube channel analytics β€” summary KPIs, subscriber / engagement / views / watch-time trends, traffic sources, sharing, top and least videos, performance schedule, and AI-generated highlights." }, { "name": "βœ… Approval Workflows", "description": "Multi-level approval workflow management for posts" }, { "name": "πŸ“₯ Bulk Automations", "description": "Submit bulk post files and act on the rows they produce" }, { "name": "♻️ Evergreen Automations", "description": "Create and manage evergreen recycling automations" }, { "name": "πŸ” RSS Automations", "description": "Create and manage RSS feed automations" }, { "name": "🧠 Brand Knowledge", "description": "Read and edit the workspace brand used by AI generation β€” the same brand the Brand Knowledge editor shows." }, { "name": "πŸ“‚ Campaigns", "description": "Campaigns management" }, { "name": "πŸ’¬ Comments", "description": "Post comments management" }, { "name": "πŸ“ Content Categories", "description": "Content categories management" }, { "name": "πŸ—“οΈ Content Category Slots", "description": "Weekly posting schedule for a content category" }, { "name": "πŸ“₯ Inbox: Items", "description": "Search and triage inbox items β€” the conversations, posts and reviews that appear in the inbox list. Also the contact profile behind an item.", "x-displayName": "Inbox Items" }, { "name": "πŸ“₯ Inbox: Messages", "description": "Direct messages in a conversation: read the thread, send a reply, add internal notes, and star messages.", "x-displayName": "Messages & DMs" }, { "name": "πŸ“₯ Inbox: Comments", "description": "Comments on posts: read the thread, reply publicly or privately, hide, like, and delete.", "x-displayName": "Post Comments" }, { "name": "πŸ“₯ Inbox: Reviews", "description": "Google Business Profile reviews: add, replace or remove your reply.", "x-displayName": "Reviews" }, { "name": "πŸ“₯ Inbox: Tags", "description": "Workspace inbox tags: list, create, rename, merge and delete.", "x-displayName": "Tags" }, { "name": "🏷️ Labels", "description": "Labels management" }, { "name": "πŸ“Š Limits & Usage", "description": "Plan entitlements and current consumption" }, { "name": "πŸ“ Content Library", "description": "Content library management" }, { "name": "πŸ”— Share Links", "description": "Public, tokenized links to a planner calendar or post list" }, { "name": "πŸ‘€ Authentication", "description": "API key validation and user authentication endpoints. Use these to verify your API key and get user information." }, { "name": "🏒 Workspaces", "description": "Workspace management and permissions. Workspaces help organize your content and team members." }, { "name": "πŸ“± Social Accounts", "description": "Connect and manage social media accounts across platforms like Facebook, Instagram, Twitter, LinkedIn, and more." }, { "name": "πŸ”— Account Connection", "description": "Initiate OAuth-based account connections, reconnect expired tokens, and add credential-based accounts (Bluesky, Facebook Group)." }, { "name": "πŸ“ Posts", "description": "Create, schedule, and manage social media posts. This is the core functionality for content publishing." }, { "name": "πŸ‘₯ Team Members", "description": "Workspace team members management" }, { "name": "πŸͺ Webhooks", "description": "Outbound webhook endpoints owned by the API key's user. A webhook receives events from every workspace its owner is an owner or admin of; it is not bound to one workspace. The `{workspace_id}` in each path only decides whose API credits the call uses (any workspace you are a member of) β€” the same webhooks come back under every workspace. Each call uses one API credit, like other workspace endpoints. Webhooks created here appear in the ContentStudio settings screen and vice versa." }, { "name": "βš™οΈ Account Preferences", "description": "βš™οΈ Account Preferences" }, { "name": "πŸ“Š Competitor Reports", "description": "πŸ“Š Competitor Reports" }, { "name": "πŸ“˜ Facebook Competitors", "description": "πŸ“˜ Facebook Competitors" }, { "name": "πŸ“Έ Instagram Competitors", "description": "πŸ“Έ Instagram Competitors" }, { "name": "πŸ—“ Report Schedules", "description": "πŸ—“ Report Schedules" }, { "name": "πŸ“„ Analytics Reports", "description": "πŸ“„ Analytics Reports" }, { "name": "πŸ”— Analytics Share Links", "description": "πŸ”— Analytics Share Links" }, { "name": "🏒 Workspace Reports", "description": "🏒 Workspace Reports" }, { "name": "⏳ Approval Cascade Jobs", "description": "⏳ Approval Cascade Jobs" }, { "name": "πŸ•’ Scheduling", "description": "πŸ•’ Scheduling" } ], "x-tagGroups": [ { "name": "Analytics", "tags": [ "πŸ“Š Analytics: Bluesky", "πŸ—‚οΈ Campaigns & Labels", "πŸ“˜ Facebook", "πŸ” Google Ads", "πŸ“ Google My Business", "πŸ“Έ Instagram", "πŸ’Ό LinkedIn", "♾️ Meta Ads", "πŸ“Œ Pinterest", "πŸ“Š Analytics: Threads", "🎡 TikTok", "βœ–οΈ X/Twitter", "▢️ YouTube" ] }, { "name": "Inbox", "tags": [ "πŸ“₯ Inbox: Comments", "πŸ“₯ Inbox: Items", "πŸ“₯ Inbox: Messages", "πŸ“₯ Inbox: Reviews", "πŸ“₯ Inbox: Tags" ] }, { "name": "Managements", "tags": [ "πŸ”— Account Connection", "βœ… Approval Workflows", "⏳ Approval Cascade Jobs", "πŸ‘€ Authentication", "🧠 Brand Knowledge", "πŸ“₯ Bulk Automations", "πŸ“‚ Campaigns", "πŸ“ Content Categories", "πŸ—“οΈ Content Category Slots", "πŸ“ Content Library", "♻️ Evergreen Automations", "🏷️ Labels", "πŸ“Š Limits & Usage", "πŸ” RSS Automations", "πŸ”— Share Links", "πŸ“± Social Accounts", "πŸ‘₯ Team Members", "πŸͺ Webhooks", "🏒 Workspaces" ] }, { "name": "Posting", "tags": [ "πŸ’¬ Comments", "πŸ“ Posts", "πŸ•’ Scheduling" ] }, { "name": "AI Generation", "tags": [ "🎠 AI Carousels", "🎨 AI Images", "🎬 AI Videos" ] } ] }