{ "openapi": "3.0.3", "info": { "title": "CuteDyno API", "version": "1.0.0", "description": "Moderate Facebook and Instagram comments on behalf of your own customers. Every resource lives inside a profile, so one API key can serve many customers.\n\n**Terminology:** The dashboard calls connected social logins \"accounts\"; the API uses `accountId` everywhere an account is referenced. Pass `profileId` to target a specific customer profile, or omit it to use the API key's home profile.\n\n**Agent surfaces:** REST (`/v1`), stdio MCP (`cutedyno mcp`), and JSON CLI (`cutedyno comments:list`). Each operation includes `x-cli-command` and `x-mcp-tool` for codegen.", "contact": { "url": "https://cutedyno.com/docs" } }, "servers": [ { "url": "https://api.cutedyno.com", "description": "Production" }, { "url": "http://localhost:3000", "description": "Local development" } ], "tags": [ { "name": "Profiles", "description": "A profile is one customer of your platform. It owns connected Facebook and Instagram accounts and comments." }, { "name": "API keys", "description": "Mint and revoke keys, optionally scoped to specific profiles." }, { "name": "Accounts", "description": "Connect Facebook and Instagram accounts to a profile and list what is connected." }, { "name": "Comments", "description": "Read Facebook and Instagram comments." }, { "name": "Webhooks", "description": "Receive comment and connection events instead of polling. Includes delivery logs and tests." } ], "security": [ { "apiKey": [] } ], "paths": { "/v1/profiles": { "get": { "operationId": "listProfiles", "summary": "List profiles", "description": "Returns every profile this API key can act on. A profile is one customer of your platform: it owns its own connected Facebook and Instagram accounts and comments.\n\n\n\n**Required permission:** `connections:read`", "tags": [ "Profiles" ], "x-permission": "connections:read", "x-profile-scoped": false, "x-cli-command": "profiles:list", "x-mcp-tool": "list_profiles", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } }, "total": { "type": "number" } }, "required": [ "profiles", "total" ], "additionalProperties": false }, "example": { "profiles": [ { "id": "prof_abc123", "name": "Acme Corp", "slug": "acme-corp", "isDefault": true, "createdAt": "2026-01-15T10:00:00.000Z" } ] } } } }, "401": { "description": "Possible codes: authentication_required, invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: insufficient_permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createProfile", "summary": "Create a profile", "description": "Creates a profile for one of your customers. Requires an account-wide key; profile-scoped keys cannot create profiles.\n\n\n\n**Required permission:** `connections:write`", "tags": [ "Profiles" ], "x-permission": "connections:write", "x-profile-scoped": false, "x-cli-command": "profiles:create", "x-mcp-tool": "create_profile", "x-idempotent": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key so a retried request is not applied twice. Stored for 24 hours.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name, usually your customer’s name." }, "description": { "type": "string", "description": "Free-form note about this customer." } }, "required": [ "name" ] }, "example": { "name": "Acme Corp", "slug": "acme-corp" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/Profile" } }, "required": [ "profile" ], "additionalProperties": false }, "example": { "profile": { "id": "prof_abc123", "name": "Acme Corp", "slug": "acme-corp", "isDefault": false, "createdAt": "2026-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Possible codes: invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: insufficient_permission, plan_limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/profiles/{id}": { "get": { "operationId": "getProfile", "summary": "Get a profile", "description": "Fetches one profile by id.\n\n\n\n**Required permission:** `connections:read`", "tags": [ "Profiles" ], "x-permission": "connections:read", "x-profile-scoped": false, "x-cli-command": "profiles:get", "x-mcp-tool": "get_profile", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Profile id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/Profile" } }, "required": [ "profile" ], "additionalProperties": false }, "example": { "profile": { "id": "prof_abc123", "name": "Acme Corp", "slug": "acme-corp", "isDefault": true, "createdAt": "2026-01-15T10:00:00.000Z" } } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: profile_not_accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Possible codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateProfile", "summary": "Update a profile", "description": "Renames a profile or changes its description.\n\n\n\n**Required permission:** `connections:write`", "tags": [ "Profiles" ], "x-permission": "connections:write", "x-profile-scoped": false, "x-cli-command": "profiles:update", "x-mcp-tool": "update_profile", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Profile id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "nullable": true, "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/Profile" } }, "required": [ "profile" ], "additionalProperties": false } } } }, "400": { "description": "Possible codes: invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: profile_not_accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Possible codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteProfile", "summary": "Delete a profile", "description": "Deletes a profile and everything inside it. Disconnect its social accounts first so their tokens are revoked deliberately.\n\n\n\n**Required permission:** `connections:write`", "tags": [ "Profiles" ], "x-permission": "connections:write", "x-profile-scoped": false, "x-cli-command": "profiles:delete", "x-mcp-tool": "delete_profile", "x-destructive": true, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Profile id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false } } } }, "400": { "description": "Possible codes: invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: profile_not_accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Possible codes: profile_has_connected_accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/profile": { "get": { "operationId": "getCurrentProfile", "summary": "Get the current profile", "description": "Returns the profile this request resolved to, which is the key’s home profile unless you passed profileId.\n\n\n\n**Required permission:** `connections:read`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Profiles" ], "x-permission": "connections:read", "x-profile-scoped": true, "x-cli-command": "profiles:current", "x-mcp-tool": "get_profile", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/Profile" } }, "required": [ "profile" ], "additionalProperties": false } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: profile_not_accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Possible codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "description": "Lists the keys in this account. Secrets are never returned.\n\n\n\n**Required permission:** `connections:read`", "tags": [ "API keys" ], "x-permission": "connections:read", "x-profile-scoped": false, "x-cli-command": "api-keys:list", "x-mcp-tool": "list_api_keys", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "keys" ], "additionalProperties": false } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: insufficient_permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createApiKey", "summary": "Create an API key", "description": "Mints a key, optionally scoped to specific profiles. The secret is returned once and cannot be retrieved later.\n\n\n\n**Required permission:** `connections:write`", "tags": [ "API keys" ], "x-permission": "connections:write", "x-profile-scoped": false, "x-cli-command": "api-keys:create", "x-mcp-tool": "create_api_key", "x-idempotent": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key so a retried request is not applied twice. Stored for 24 hours.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Label shown in the dashboard." }, "profileIds": { "type": "array", "items": { "type": "string" }, "description": "Restrict the key to these profiles. Omit for access to every profile in the account." }, "expiresIn": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "Days until the key expires. Omit for no expiry." }, "allowedAccountIds": { "type": "array", "items": { "type": "string" }, "description": "Restrict the key to these connected accounts." }, "maxPostsPerDay": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Cap usage per UTC day with this key." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "type": "string", "description": "The only time the full key is returned." }, "message": { "type": "string" } }, "required": [ "key", "secret", "message" ], "additionalProperties": false } } } }, "400": { "description": "Possible codes: invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: insufficient_permission, profile_not_accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys/{id}": { "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "description": "Deactivates a key immediately. A key cannot revoke itself.\n\n\n\n**Required permission:** `connections:write`", "tags": [ "API keys" ], "x-permission": "connections:write", "x-profile-scoped": false, "x-cli-command": "api-keys:revoke", "x-mcp-tool": "revoke_api_key", "x-destructive": true, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "revoked", "id" ], "additionalProperties": false } } } }, "400": { "description": "Possible codes: invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Possible codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/accounts": { "get": { "operationId": "listAccounts", "summary": "List connected accounts", "description": "Lists the social accounts connected to a profile. Use `id` everywhere an account id is asked for; `platformAccountId` is the platform’s own id and is accepted too.\n\n\n\n**Required permission:** `connections:read`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Accounts" ], "x-permission": "connections:read", "x-profile-scoped": true, "x-cli-command": "accounts:list", "x-mcp-tool": "list_accounts", "parameters": [ { "name": "profileId", "in": "query", "required": false, "description": "Profile to act on. Defaults to the profile the API key was created in.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "profileId": { "type": "string" } }, "required": [ "accounts", "profileId" ], "additionalProperties": false }, "example": { "profileId": "prof_abc123", "accounts": [ { "id": "acct_1", "platform": "instagram", "platformAccountId": "17841400000000000", "username": "acme", "displayName": "Acme Corp", "profileId": "prof_abc123", "connectedAt": "2026-01-10T08:00:00.000Z" } ] } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: profile_not_accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connect/{platform}": { "get": { "operationId": "startConnect", "summary": "Start a connect flow", "description": "Creates a connect session and returns the URL to send your customer to. Equivalent to POST /v1/connect/sessions.\n\n\n\n**Required permission:** `connections:write`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Accounts" ], "x-permission": "connections:write", "x-profile-scoped": true, "x-cli-command": "accounts:connect", "x-mcp-tool": "start_connect", "parameters": [ { "name": "platform", "in": "path", "required": true, "description": "One of facebook, instagram, tiktok, linkedin, youtube.", "schema": { "type": "string" } }, { "name": "profileId", "in": "query", "required": false, "description": "Profile to act on. Defaults to the profile the API key was created in.", "schema": { "type": "string" } }, { "name": "redirectUrl", "in": "query", "required": false, "description": "HTTPS URL to return the user to once they finish.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "authUrl": { "type": "string" }, "state": { "type": "string" }, "session": { "$ref": "#/components/schemas/ConnectSession" } }, "required": [ "authUrl", "state", "session" ], "additionalProperties": false }, "example": { "authUrl": "https://api.cutedyno.com/v1/connect/instagram/authorize?state=...", "state": "sess_xyz", "session": { "id": "sess_xyz", "platform": "instagram", "status": "pending", "profileId": "prof_abc123", "createdAt": "2026-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Possible codes: invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: profile_not_accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connect/sessions": { "post": { "operationId": "createConnectSession", "summary": "Create a connect session", "description": "Starts an OAuth flow for one profile and returns the URL to redirect your customer to.\n\n\n\n**Required permission:** `connections:write`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Accounts" ], "x-permission": "connections:write", "x-profile-scoped": true, "x-cli-command": "accounts:connect-session", "x-mcp-tool": "create_connect_session", "x-idempotent": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key so a retried request is not applied twice. Stored for 24 hours.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Profile to act on. Defaults to the profile the API key was created in." }, "platform": { "$ref": "#/components/schemas/Platform" }, "redirectUrl": { "type": "string", "description": "HTTPS URL to return the user to once they finish." } }, "required": [ "platform" ] }, "example": { "platform": "instagram", "profileId": "prof_abc123" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "authUrl": { "type": "string" }, "state": { "type": "string" }, "session": { "$ref": "#/components/schemas/ConnectSession" } }, "required": [ "authUrl", "state", "session" ], "additionalProperties": false }, "example": { "authUrl": "https://api.cutedyno.com/v1/connect/instagram/authorize?state=...", "state": "sess_xyz", "session": { "id": "sess_xyz", "platform": "instagram", "status": "pending", "profileId": "prof_abc123", "createdAt": "2026-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Possible codes: invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: profile_not_accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connect/sessions/{id}": { "get": { "operationId": "getConnectSession", "summary": "Get a connect session", "description": "Polls a connect session. Once status is completed, the accounts array lists what was connected.\n\n\n\n**Required permission:** `connections:read`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Accounts" ], "x-permission": "connections:read", "x-profile-scoped": true, "x-cli-command": "accounts:connect-get", "x-mcp-tool": "get_connect_session", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Connect session id.", "schema": { "type": "string" } }, { "name": "profileId", "in": "query", "required": false, "description": "Profile to act on. Defaults to the profile the API key was created in.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/ConnectSession" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } }, "required": [ "session", "accounts" ], "additionalProperties": false } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: profile_not_accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Possible codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/comments": { "get": { "operationId": "listComments", "summary": "List comments", "description": "Lists Facebook, Instagram, and TikTok comments for the profile.\n\n\n\n**Required permission:** `comments:read`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Comments" ], "x-permission": "comments:read", "x-profile-scoped": true, "x-cli-command": "comments:list", "x-mcp-tool": "list_comments", "parameters": [ { "name": "profileId", "in": "query", "required": false, "description": "Profile to act on. Defaults to the profile the API key was created in.", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "facebook", "instagram", "tiktok" ] } }, { "name": "accountId", "in": "query", "required": false, "description": "Restrict to one account. Either `id` or `platformAccountId` from GET /v1/accounts.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from a previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }, "nextCursor": { "nullable": true, "type": "string" } }, "required": [ "comments", "nextCursor" ], "additionalProperties": false } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: profile_not_accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhook subscriptions", "description": "Lists the webhook endpoints registered for a profile.\n\n\n\n**Required permission:** `webhooks:read`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Webhooks" ], "x-permission": "webhooks:read", "x-profile-scoped": true, "x-cli-command": "webhooks:list", "x-mcp-tool": "list_webhooks", "parameters": [ { "name": "profileId", "in": "query", "required": false, "description": "Profile to act on. Defaults to the profile the API key was created in.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "supportedEvents": { "type": "array", "items": { "type": "string" } } }, "required": [ "subscriptions", "supportedEvents" ], "additionalProperties": false }, "example": { "webhooks": [ { "id": "wh_1", "url": "https://example.com/webhooks/cutedyno", "events": [ "comment.received" ], "isActive": true, "profileId": "prof_abc123", "createdAt": "2026-01-15T10:00:00.000Z" } ] } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: insufficient_permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createWebhook", "summary": "Create a webhook subscription", "description": "Registers an endpoint. Set scope to account to receive events from every profile through one endpoint. The signing secret is returned once.\n\n\n\n**Required permission:** `webhooks:write`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Webhooks" ], "x-permission": "webhooks:write", "x-profile-scoped": true, "x-cli-command": "webhooks:create", "x-mcp-tool": "create_webhook", "x-idempotent": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key so a retried request is not applied twice. Stored for 24 hours.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Profile to act on. Defaults to the profile the API key was created in." }, "url": { "type": "string", "description": "HTTPS endpoint that receives POSTs." }, "events": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "description": "Event types to subscribe to, or [\"*\"] for everything." }, "scope": { "allOf": [ { "$ref": "#/components/schemas/WebhookScope" } ], "description": "Defaults to profile." } }, "required": [ "url", "events" ] }, "example": { "url": "https://example.com/webhooks/cutedyno", "events": [ "comment.received" ], "profileId": "prof_abc123" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/WebhookSubscription" }, "secret": { "type": "string", "description": "Use this to verify the CuteDyno-Signature header." }, "retrySchedule": { "type": "array", "items": { "type": "number" }, "description": "Retry delays in seconds." } }, "required": [ "subscription", "secret", "retrySchedule" ], "additionalProperties": false }, "example": { "webhook": { "id": "wh_1", "url": "https://example.com/webhooks/cutedyno", "events": [ "comment.received" ], "isActive": true, "profileId": "prof_abc123", "secret": "whsec_...", "createdAt": "2026-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Possible codes: invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Possible codes: insufficient_permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test event", "description": "Delivers a synthetic event so you can verify your endpoint and signature check before waiting on real activity.\n\n\n\n**Required permission:** `webhooks:write`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Webhooks" ], "x-permission": "webhooks:write", "x-profile-scoped": true, "x-cli-command": "webhooks:test", "x-mcp-tool": "test_webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Profile to act on. Defaults to the profile the API key was created in." }, "eventType": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" } ], "description": "Event type to simulate. Defaults to comment.received." } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "eventType", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "delivery" ], "additionalProperties": false } } } }, "400": { "description": "Possible codes: invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Possible codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List webhook deliveries", "description": "Returns the delivery log for one subscription, including response codes and the next scheduled retry.\n\n\n\n**Required permission:** `webhooks:read`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Webhooks" ], "x-permission": "webhooks:read", "x-profile-scoped": true, "x-cli-command": "webhooks:deliveries", "x-mcp-tool": "list_webhook_deliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription id.", "schema": { "type": "string" } }, { "name": "profileId", "in": "query", "required": false, "description": "Profile to act on. Defaults to the profile the API key was created in.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "delivered", "failed", "all" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1-100. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "total": { "type": "number" }, "maxAttempts": { "type": "number" }, "retrySchedule": { "type": "array", "items": { "type": "number" } }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": [ "deliveries", "total", "maxAttempts", "retrySchedule", "limit", "offset" ], "additionalProperties": false } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Possible codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "patch": { "operationId": "updateWebhook", "summary": "Update a webhook subscription", "description": "Changes the URL or event list, or pauses delivery with isActive: false. A paused subscription keeps its secret and its delivery history.\n\n\n\n**Required permission:** `webhooks:write`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Webhooks" ], "x-permission": "webhooks:write", "x-profile-scoped": true, "x-cli-command": "webhooks:update", "x-mcp-tool": "update_webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Profile to act on. Defaults to the profile the API key was created in." }, "url": { "type": "string", "description": "HTTPS endpoint that receives POSTs." }, "events": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "description": "Replaces the current event list." }, "isActive": { "type": "boolean", "description": "Set false to stop delivering without deleting." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/WebhookSubscription" } }, "required": [ "subscription" ], "additionalProperties": false } } } }, "400": { "description": "Possible codes: invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Possible codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook subscription", "description": "Removes an endpoint. In-flight retries stop.\n\n\n\n**Required permission:** `webhooks:write`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Webhooks" ], "x-permission": "webhooks:write", "x-profile-scoped": true, "x-cli-command": "webhooks:delete", "x-mcp-tool": "delete_webhook", "x-destructive": true, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Possible codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate the signing secret", "description": "Issues a new signing secret and returns it once. The previous secret stops verifying immediately, so deploy the new one before the next event.\n\n\n\n**Required permission:** `webhooks:write`\n\nAccepts `profileId` to target a specific profile. Omit it to use the key’s home profile.", "tags": [ "Webhooks" ], "x-permission": "webhooks:write", "x-profile-scoped": true, "x-cli-command": "webhooks:rotate-secret", "x-mcp-tool": "rotate_webhook_secret", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "description": "Profile to act on. Defaults to the profile the API key was created in." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string", "description": "Shown once. Use it to verify the CuteDyno-Signature header." } }, "required": [ "id", "secret" ], "additionalProperties": false } } } }, "401": { "description": "Possible codes: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Possible codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Possible codes: rate_limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Possible codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Send your key as `Authorization: Bearer cdyn_live_...`. Create one in the dashboard under Developers." } }, "schemas": { "Platform": { "type": "string", "enum": [ "facebook", "instagram", "tiktok" ], "description": "Social platform identifier." }, "PostStatus": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "rejected", "scheduled", "queued", "processing", "published", "partially_published", "failed", "cancelled" ], "description": "Lifecycle state of a post." }, "ContentType": { "type": "string", "enum": [ "text", "image", "video" ], "description": "Shape of the content being published." }, "ApiKeyScope": { "type": "string", "enum": [ "full", "agent", "readonly" ], "description": "Permission preset on an API key. New keys are always full." }, "WebhookEvent": { "type": "string", "enum": [ "account.connected", "account.disconnected", "connection.completed", "connection.failed", "comment.received", "conversation.started", "message.received", "message.sent", "message.edited", "message.deleted", "message.delivered", "message.read", "message.failed", "reaction.received", "lead.received", "ad.status_changed" ], "description": "A webhook event type. Use \"*\" to subscribe to all of them." }, "WebhookScope": { "type": "string", "enum": [ "profile", "account" ], "description": "profile receives events from one profile; account receives events from every profile in the account." }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation." }, "docsUrl": { "type": "string", "description": "Link to the documentation for this code." }, "requestId": { "nullable": true, "description": "Echo of X-Request-Id, useful when reporting an issue.", "type": "string" }, "details": { "description": "Extra machine-readable context." } }, "required": [ "code", "message", "docsUrl", "requestId" ], "additionalProperties": false }, "message": { "type": "string", "description": "Convenience copy of error.message." } }, "required": [ "error", "message" ], "additionalProperties": false }, "Profile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "updatedAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "name", "description", "createdAt", "updatedAt" ], "additionalProperties": false }, "Account": { "type": "object", "properties": { "id": { "type": "string", "description": "CuteDyno id for the account. Pass this in `accountIds` and in the comment filters." }, "platformAccountId": { "type": "string", "description": "The platform’s own id, for reconciling with data you already hold. Also accepted anywhere `id` is." }, "accountId": { "nullable": true, "description": "Deprecated alias of `id`. Will be removed in a future version.", "type": "string" }, "platform": { "$ref": "#/components/schemas/Platform" }, "name": { "type": "string" }, "username": { "nullable": true, "type": "string" }, "profilePictureUrl": { "nullable": true, "type": "string" }, "connectedAt": { "nullable": true, "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "platformAccountId", "accountId", "platform", "name", "username", "profilePictureUrl", "connectedAt" ], "additionalProperties": false }, "PostAccount": { "type": "object", "properties": { "id": { "type": "string", "description": "CuteDyno id for the account." }, "platformAccountId": { "type": "string", "description": "The platform’s own id." }, "platform": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "platformAccountId", "platform", "name" ], "additionalProperties": false }, "MediaItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false }, "PostResult": { "type": "object", "properties": { "targetId": { "type": "string", "description": "CuteDyno id of the account this result belongs to." }, "platform": { "$ref": "#/components/schemas/Platform" }, "pageName": { "type": "string", "description": "Account name at the time of publishing." }, "status": { "type": "string", "enum": [ "success", "failed" ] }, "result": { "description": "The platform’s own response on success, including its post id where it returns one." }, "error": { "description": "Why this account failed. Present only when status is failed.", "type": "string" } }, "required": [ "targetId", "platform", "pageName", "status" ], "additionalProperties": false }, "PostSummary": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/PostStatus" }, "content": { "type": "string" }, "contentType": { "$ref": "#/components/schemas/ContentType" }, "scheduledAt": { "nullable": true, "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/PostAccount" } } }, "required": [ "id", "status", "content", "contentType", "scheduledAt", "createdAt", "accounts" ], "additionalProperties": false }, "Post": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/PostStatus" }, "content": { "type": "string" }, "contentType": { "$ref": "#/components/schemas/ContentType" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } }, "platforms": { "description": "Per-platform options that were applied to this post.", "type": "object", "additionalProperties": {} }, "scheduledAt": { "nullable": true, "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "updatedAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "completedAt": { "nullable": true, "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/PostAccount" } }, "results": { "nullable": true, "description": "One entry per target account, written as publishing completes. Null until the post starts publishing.", "type": "array", "items": { "$ref": "#/components/schemas/PostResult" } }, "completedTargets": { "type": "number" }, "failedTargets": { "type": "number" }, "totalTargets": { "type": "number" } }, "required": [ "id", "status", "content", "contentType", "media", "scheduledAt", "createdAt", "updatedAt", "completedAt", "accounts", "results", "completedTargets", "failedTargets", "totalTargets" ], "additionalProperties": false }, "Comment": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "message": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "authorUsername": { "nullable": true, "type": "string" }, "isHidden": { "type": "boolean" }, "hasResponse": { "type": "boolean" }, "responseText": { "nullable": true, "type": "string" }, "postId": { "nullable": true, "type": "string" }, "parentId": { "nullable": true, "type": "string" }, "account": { "type": "object", "properties": { "accountId": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" }, "profilePictureUrl": { "nullable": true, "type": "string" } }, "required": [ "accountId", "name", "platform", "profilePictureUrl" ], "additionalProperties": false }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "postedAt": { "nullable": true, "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "platform", "message", "authorId", "authorName", "authorUsername", "isHidden", "hasResponse", "responseText", "postId", "parentId", "account", "createdAt", "postedAt" ], "additionalProperties": false }, "ConnectSession": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "$ref": "#/components/schemas/Platform" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed", "expired" ] }, "authUrl": { "type": "string" }, "url": { "description": "Deprecated alias for authUrl.", "type": "string" }, "errorMessage": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "completedAt": { "nullable": true, "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "expiresAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "platform", "status", "errorMessage", "completedAt" ], "additionalProperties": false }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types, or [\"*\"] for everything." }, "scope": { "$ref": "#/components/schemas/WebhookScope" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "updatedAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "url", "events", "scope", "isActive", "createdAt" ], "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "Also sent as the CuteDyno-Event-Id header, for deduplication." }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "number" }, "responseStatus": { "nullable": true, "type": "number" }, "responseBody": { "nullable": true, "type": "string" }, "lastAttemptAt": { "nullable": true, "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "nextAttemptAt": { "nullable": true, "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "eventType", "status", "attempts", "responseStatus", "responseBody", "lastAttemptAt", "nextAttemptAt", "createdAt" ], "additionalProperties": false }, "Policy": { "type": "object", "properties": { "requireApproval": { "type": "boolean" }, "allowedPlatforms": { "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/Platform" } }, "maxPostsPerDay": { "nullable": true, "type": "number" } }, "required": [ "requireApproval", "allowedPlatforms", "maxPostsPerDay" ], "additionalProperties": false }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "keyPrefix": { "type": "string", "description": "First characters of the key, for display." }, "scope": { "$ref": "#/components/schemas/ApiKeyScope" }, "profileIds": { "nullable": true, "description": "null means the key can reach every profile in the account.", "type": "array", "items": { "type": "string" } }, "expiresAt": { "nullable": true, "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "name", "keyPrefix", "scope", "profileIds", "expiresAt", "createdAt" ], "additionalProperties": false }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "string" }, "actorType": { "type": "string", "enum": [ "api_key", "user", "system" ] }, "action": { "type": "string" }, "resourceType": { "type": "string" }, "resourceId": { "nullable": true, "type": "string" }, "apiKeyId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "metadata": { "nullable": true }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "actorType", "action", "resourceType", "resourceId", "apiKeyId", "userId", "metadata", "createdAt" ], "additionalProperties": false }, "ApiRequestLog": { "type": "object", "properties": { "id": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "statusCode": { "type": "number" }, "durationMs": { "nullable": true, "type": "number" }, "requestId": { "type": "string" }, "errorMessage": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "method", "path", "statusCode", "durationMs", "requestId", "errorMessage", "createdAt" ], "additionalProperties": false }, "MediaUploadSessionFile": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "url": { "type": "string" }, "fileName": { "type": "string" } }, "required": [ "type", "url", "fileName" ], "additionalProperties": false }, "MediaUploadSession": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "expired" ] }, "uploadUrl": { "type": "string" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/MediaUploadSessionFile" } }, "expiresAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "createdAt": { "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." }, "completedAt": { "nullable": true, "type": "string", "description": "ISO 8601 datetime, for example 2026-08-01T12:00:00Z." } }, "required": [ "id", "status", "uploadUrl", "files", "expiresAt", "createdAt", "completedAt" ], "additionalProperties": false }, "WorkspaceAnalytics": { "type": "object", "properties": { "profileId": { "type": "string" }, "summary": { "type": "object", "properties": { "followers": { "type": "number" }, "totalViews": { "type": "number" }, "periodViews": { "type": "number" }, "periodLikes": { "type": "number" }, "periodComments": { "type": "number" }, "periodShares": { "type": "number" }, "periodSaves": { "type": "number" }, "periodReach": { "type": "number" }, "accountsConnected": { "type": "number" } }, "required": [ "followers", "totalViews", "periodViews", "periodLikes", "periodComments", "periodShares", "periodSaves", "periodReach", "accountsConnected" ], "additionalProperties": false }, "accounts": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "summary", "accounts" ], "additionalProperties": false }, "WorkspaceAnalyticsHistory": { "type": "object", "properties": { "profileId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "previousFrom": { "type": "string" }, "previousTo": { "type": "string" }, "snapshotDays": { "type": "number" }, "hasHistory": { "type": "boolean" }, "summary": { "type": "object", "properties": { "views": { "type": "object", "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "delta": { "type": "number" }, "deltaPercent": { "nullable": true, "type": "number" } }, "required": [ "value", "previousValue", "delta", "deltaPercent" ], "additionalProperties": false }, "engagement": { "type": "object", "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "delta": { "type": "number" }, "deltaPercent": { "nullable": true, "type": "number" } }, "required": [ "value", "previousValue", "delta", "deltaPercent" ], "additionalProperties": false }, "shares": { "type": "object", "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "delta": { "type": "number" }, "deltaPercent": { "nullable": true, "type": "number" } }, "required": [ "value", "previousValue", "delta", "deltaPercent" ], "additionalProperties": false }, "followers": { "type": "object", "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "delta": { "type": "number" }, "deltaPercent": { "nullable": true, "type": "number" } }, "required": [ "value", "previousValue", "delta", "deltaPercent" ], "additionalProperties": false }, "reach": { "type": "object", "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "delta": { "type": "number" }, "deltaPercent": { "nullable": true, "type": "number" } }, "required": [ "value", "previousValue", "delta", "deltaPercent" ], "additionalProperties": false }, "engagementRate": { "type": "object", "properties": { "value": { "type": "number" }, "previousValue": { "type": "number" }, "delta": { "type": "number" }, "deltaPercent": { "nullable": true, "type": "number" } }, "required": [ "value", "previousValue", "delta", "deltaPercent" ], "additionalProperties": false } }, "required": [ "views", "engagement", "shares", "followers", "reach", "engagementRate" ], "additionalProperties": false }, "timeseries": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "timeseriesByPlatform": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "platforms": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "topContent": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "insights": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "from", "to", "previousFrom", "previousTo", "snapshotDays", "hasHistory", "summary", "timeseries", "timeseriesByPlatform", "platforms", "topContent", "insights" ], "additionalProperties": false } } }, "x-error-codes": [ { "code": "invalid_request", "status": 400, "title": "Invalid request", "description": "The request body or query string failed validation. The message names the offending field.", "retryable": false }, { "code": "invalid_profile_id", "status": 400, "title": "Invalid profile id", "description": "profileId was supplied but was not a string.", "retryable": false }, { "code": "invalid_scheduled_at", "status": 400, "title": "Invalid scheduledAt", "description": "scheduledAt could not be parsed as an ISO 8601 datetime, or it is in the past.", "retryable": false }, { "code": "invalid_state_transition", "status": 400, "title": "Invalid state transition", "description": "The post is in a state that does not allow this operation, for example editing a post that already published.", "retryable": false }, { "code": "key_not_linked_to_user", "status": 400, "title": "API key not linked to a user", "description": "Publishing records a human actor. Recreate the key from the dashboard so it carries an owner.", "retryable": false }, { "code": "authentication_required", "status": 401, "title": "Authentication required", "description": "No Authorization header was sent, or it was not a Bearer token.", "retryable": false }, { "code": "invalid_api_key", "status": 401, "title": "Invalid API key", "description": "The key does not exist, was revoked, or is malformed. Keys start with cdyn_live_.", "retryable": false }, { "code": "api_key_expired", "status": 401, "title": "API key expired", "description": "The key passed its expiresAt date. Create a replacement key.", "retryable": false }, { "code": "trial_expired", "status": 402, "title": "Trial expired", "description": "The account trial ended. Billing affects every profile at once, so alert an operator instead of retrying.", "retryable": false }, { "code": "insufficient_permission", "status": 403, "title": "Insufficient permission", "description": "The key is missing the scope this endpoint needs, for example posts:write on a readonly key.", "retryable": false }, { "code": "profile_not_accessible", "status": 403, "title": "Profile not accessible", "description": "The requested profile is outside this key’s scope, or belongs to another account.", "retryable": false }, { "code": "plan_limit", "status": 403, "title": "Plan limit reached", "description": "A plan quota was exhausted. The response carries entitlement, usage, and limit so you can surface the reason.", "retryable": false }, { "code": "account_not_allowed", "status": 403, "title": "Account not allowed", "description": "The key is restricted to specific connected accounts and one of the supplied accountIds is not among them.", "retryable": false }, { "code": "platform_not_allowed", "status": 403, "title": "Platform not allowed", "description": "The profile policy restricts which platforms may be posted to, and one of the target accounts is on a platform outside that list.", "retryable": false }, { "code": "approval_required", "status": 403, "title": "Approval required", "description": "This profile or key forces posts through review, and no approver could be determined. Supply approvers, or recreate the key so it carries an owner.", "retryable": false }, { "code": "daily_post_limit", "status": 403, "title": "Daily post limit reached", "description": "The key has a maxPostsPerDay cap and it has been reached. The cap resets at midnight UTC.", "retryable": false }, { "code": "not_found", "status": 404, "title": "Not found", "description": "The resource does not exist inside the resolved profile.", "retryable": false }, { "code": "no_accounts_connected", "status": 404, "title": "No accounts connected", "description": "The profile has no connected social accounts yet. Run the connect flow first.", "retryable": false }, { "code": "accounts_not_found", "status": 404, "title": "Accounts not found", "description": "None of the supplied accountIds matched a connected account in this profile.", "retryable": false }, { "code": "idempotency_key_reused", "status": 409, "title": "Idempotency key reused", "description": "This Idempotency-Key was already used with a different request body. Use a fresh key.", "retryable": false }, { "code": "profile_has_connected_accounts", "status": 409, "title": "Profile still has connected accounts", "description": "Disconnect the profile’s social accounts before deleting it, so tokens are revoked deliberately.", "retryable": false }, { "code": "unsupported_media_type", "status": 415, "title": "Unsupported media type", "description": "The fileType passed to POST /v1/media/upload is not an accepted image or video type.", "retryable": false }, { "code": "rate_limit_exceeded", "status": 429, "title": "Rate limit exceeded", "description": "Too many requests for this key. Honour the Retry-After header before retrying.", "retryable": true }, { "code": "internal_error", "status": 500, "title": "Internal error", "description": "Something failed on our side. Retry with the same Idempotency-Key; report the requestId if it persists.", "retryable": true } ] }