{ "openapi": "3.1.0", "info": { "title": "Dystro API", "version": "1.0.0", "description": "Unified social posting & analytics. Behavioural rules for agents: https://app.dystro.dev/agents.txt · Full guide: https://app.dystro.dev/llms-full.txt" }, "servers": [ { "url": "https://lovable-anaconda-804.convex.site" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Org-wide API key from Settings → API keys, or an OAuth 2.1 access token from \"Sign in with Dystro\". The project is a per-call argument, not part of the credential." } }, "schemas": { "ErrorEnvelope": { "type": "object", "properties": { "code": { "type": "string" }, "human_message": { "type": "string" }, "remediation": { "type": "string" }, "retry_strategy": { "type": "string", "enum": [ "none", "immediate", "backoff", "manual" ] }, "retry_after_ms": { "type": "number" }, "trace_id": { "type": "string" }, "cause": { "type": "string" }, "violations": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "code": { "type": "string" }, "rule": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "code", "human_message", "remediation", "retry_strategy", "trace_id" ] }, "MediaItem": { "type": "object", "properties": { "mediaId": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video", "gif" ] }, "mimeType": { "type": "string" }, "bytes": { "type": "number" }, "durationMs": { "type": "number" }, "altText": { "type": "string", "description": "Accessibility description for image/gif media." }, "aspectRatio": { "type": "object", "properties": { "width": { "type": "number" }, "height": { "type": "number" } } } }, "required": [ "kind", "mimeType", "bytes" ] }, "Leg": { "type": "object", "description": "One (post × account) delivery outcome row.", "properties": { "leg_id": { "type": "string" }, "platform": { "type": "string" }, "account_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "scheduled", "dispatching", "succeeded", "published", "failed", "cancelled" ] }, "retry_available": { "type": "boolean" }, "platform_post_id": { "type": "string" }, "url": { "type": "string" }, "latency_ms": { "type": "number" }, "error": { "$ref": "#/components/schemas/ErrorEnvelope" }, "effective_text": { "type": "string" }, "created_at": { "type": "number" }, "published_at": { "type": "number" } } }, "CreatePostBody": { "type": "object", "properties": { "projectId": { "type": "string" }, "text": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "idempotency_key": { "type": "string", "description": "Mandatory unless the Idempotency-Key header is sent. Replaying the same key returns the original post." }, "schedule": { "type": "object", "description": "{ kind: 'one_shot', scheduledFor: epoch-ms } or recurring shapes." }, "save_as_draft": { "type": "boolean" }, "overrides": { "type": "object", "description": "Per-platform diff over the base: { : { text?, media? } }." }, "platform_settings": { "type": "object", "description": "Per-platform publish settings, validated against GET /v1/platforms." }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } } }, "required": [ "projectId", "text", "platforms" ] } } }, "paths": { "/v1/status": { "get": { "operationId": "meta_get_status", "summary": "Public per-platform publish success rates with an optional sparkline.", "tags": [ "meta" ], "security": [], "responses": { "200": { "description": "Per-platform success rates + sparkline" } } } }, "/v1/platforms": { "get": { "operationId": "meta_list_platforms", "summary": "Keyless capability manifest: per-platform limits, media rules, and settings.", "tags": [ "meta" ], "security": [], "responses": { "200": { "description": "OK" } } } }, "/v1/whoami": { "get": { "operationId": "meta_whoami", "summary": "Resolve the calling credential: org, projects, scopes, and limits.", "tags": [ "meta" ], "responses": { "200": { "description": "Auth context" }, "401": { "description": "Bad key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/test-post": { "post": { "operationId": "meta_test_post", "summary": "Validate a would-be post against the capability manifest without publishing; always answers 200.", "tags": [ "meta" ], "responses": { "200": { "description": "Echo + valid/violations" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/auth/verify": { "get": { "operationId": "auth_verify", "summary": "Verify the current bearer credential.", "tags": [ "meta" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/usage": { "get": { "operationId": "usage_get", "summary": "Get organization usage and credit balances.", "tags": [ "meta" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/logs": { "get": { "operationId": "logs_list", "summary": "List API and delivery request logs.", "tags": [ "meta" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/tools/validate/post": { "post": { "operationId": "tools_validate_post", "summary": "Validate a post without publishing.", "tags": [ "meta" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/tools/validate/post-length": { "post": { "operationId": "tools_validate_post_length", "summary": "Validate post length by platform.", "tags": [ "meta" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/tools/validate/media": { "post": { "operationId": "tools_validate_media", "summary": "Validate media metadata by platform.", "tags": [ "meta" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/me/connected-apps": { "get": { "operationId": "connected_apps_list", "summary": "List OAuth apps connected by the bearer user.", "tags": [ "meta" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "delete": { "operationId": "connected_apps_delete", "summary": "Disconnect an OAuth app owned by the bearer user.", "tags": [ "meta" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts/connect": { "post": { "operationId": "accounts_connect", "summary": "Start a sandbox or hosted OAuth account connection.", "tags": [ "accounts" ], "x-required-scope": "accounts:write", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts": { "get": { "operationId": "accounts_list", "summary": "List connected accounts for a project.", "tags": [ "accounts" ], "x-required-scope": "accounts:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts/health": { "get": { "operationId": "accounts_health", "summary": "Get connector health for every account in a project.", "tags": [ "accounts" ], "x-required-scope": "accounts:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts/follower-stats": { "get": { "operationId": "accounts_follower_stats", "summary": "Get the latest follower metric for each account in a project.", "tags": [ "accounts" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts/{accountId}": { "get": { "operationId": "accounts_get", "summary": "Get one connected account with credentials redacted.", "tags": [ "accounts" ], "x-required-scope": "accounts:read", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "patch": { "operationId": "accounts_update", "summary": "Update a connected account display name.", "tags": [ "accounts" ], "x-required-scope": "accounts:write", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "delete": { "operationId": "accounts_disconnect", "summary": "Disconnect a connected social account.", "tags": [ "accounts" ], "x-required-scope": "accounts:write", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts/{accountId}/reconnect": { "post": { "operationId": "accounts_reconnect", "summary": "Start a fresh OAuth connection for a connected account.", "tags": [ "accounts" ], "x-required-scope": "accounts:write", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts/{accountId}/health": { "get": { "operationId": "accounts_get_health", "summary": "Get token expiry and recent delivery health for one account.", "tags": [ "accounts" ], "x-required-scope": "accounts:read", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts/{accountId}/subresources": { "get": { "operationId": "accounts_list_subresources", "summary": "List pages or channels available to a connected account.", "tags": [ "accounts" ], "x-required-scope": "accounts:read", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts/{accountId}/subresource": { "put": { "operationId": "accounts_select_subresource", "summary": "Select the page or channel used by a connected account.", "tags": [ "accounts" ], "x-required-scope": "accounts:write", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts/{accountId}/youtube-playlists": { "get": { "operationId": "accounts_list_youtube_playlists", "summary": "List YouTube playlists, including private playlists, and the stored default.", "tags": [ "accounts" ], "x-required-scope": "accounts:read", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "put": { "operationId": "accounts_select_youtube_playlist", "summary": "Store defaultPlaylistId (non-empty) and optional defaultPlaylistName for YouTube.", "tags": [ "accounts" ], "x-required-scope": "accounts:write", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/accounts/{accountId}/analytics": { "get": { "operationId": "accounts_get_analytics", "summary": "Get daily analytics snapshots for a connected account.", "tags": [ "accounts" ], "x-required-scope": "analytics:read", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/projects/{projectId}/analytics": { "get": { "operationId": "projects_get_analytics", "summary": "Get daily analytics aggregated across a project.", "tags": [ "accounts" ], "x-required-scope": "analytics:read", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/daily-metrics": { "get": { "operationId": "analytics_daily_metrics", "summary": "Get materialized daily project metrics, optionally filtered by platform.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/post-timeline": { "get": { "operationId": "analytics_post_timeline", "summary": "Get a post analytics timeline by day and platform.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/cross-platform": { "get": { "operationId": "analytics_cross_platform", "summary": "Compare each post across the platforms it was published to.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/best-time": { "get": { "operationId": "analytics_best_time", "summary": "Compare engagement by UTC day of week and publishing hour.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/content-decay": { "get": { "operationId": "analytics_content_decay", "summary": "Measure average post metrics for the first 14 days after publishing.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/posting-frequency": { "get": { "operationId": "analytics_posting_frequency", "summary": "Compare weekly publishing frequency with average engagement per post.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/follower-history": { "get": { "operationId": "analytics_follower_history", "summary": "Get daily follower history for every account in a project.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/sync-status": { "get": { "operationId": "analytics_sync_status", "summary": "Get analytics freshness and the automatic refresh cadence.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/refresh": { "post": { "operationId": "analytics_refresh", "summary": "Schedule an analytics refresh for one project.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/inbox/volume": { "get": { "operationId": "analytics_inbox_volume", "summary": "Get daily inbox received, replied, and resolved volume.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/inbox/response-time": { "get": { "operationId": "analytics_inbox_response_time", "summary": "Get first-response histogram and estimated p50 and p90.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/inbox/heatmap": { "get": { "operationId": "analytics_inbox_heatmap", "summary": "Get inbox volume by UTC day of week and hour.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/inbox/source-breakdown": { "get": { "operationId": "analytics_inbox_source_breakdown", "summary": "Get inbox totals grouped by platform and interaction kind.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/analytics/inbox/top-accounts": { "get": { "operationId": "analytics_inbox_top_accounts", "summary": "Rank the top 20 project accounts by received interactions.", "tags": [ "analytics" ], "x-required-scope": "analytics:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/sandbox/accounts/connect": { "post": { "operationId": "sandbox_accounts_connect", "summary": "Connect a sandbox account to a project.", "tags": [ "accounts" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/sandbox/inject": { "post": { "operationId": "sandbox_inject", "summary": "Inject a synthetic interaction into a sandbox account.", "tags": [ "accounts" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/sandbox/inject-failure": { "post": { "operationId": "sandbox_inject_failure", "summary": "Make the next sandbox publish fail with a structured error.", "tags": [ "accounts" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/connect-links": { "post": { "operationId": "connect_links_create", "summary": "Mint a hosted account-connect link for an end user.", "tags": [ "connect" ], "x-required-scope": "accounts:write", "responses": { "200": { "description": "Link created; `url` is returned once and never again" }, "400": { "description": "Project not in this org, bad TTL, unknown platform, or non-https redirectUrl", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "429": { "description": "Hourly per-org mint limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "get": { "operationId": "connect_links_list", "summary": "List hosted connect links for the organization.", "tags": [ "connect" ], "x-required-scope": "accounts:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/connect-links/{id}": { "get": { "operationId": "connect_links_get", "summary": "Get the reconciliation status of a hosted connect link.", "tags": [ "connect" ], "x-required-scope": "accounts:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "pending/used/expired/revoked + used_count" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "404": { "description": "Unknown link", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "delete": { "operationId": "connect_links_revoke", "summary": "Revoke a hosted connect link before it expires.", "tags": [ "connect" ], "x-required-scope": "accounts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the accounts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/connect/resolve": { "post": { "operationId": "connect_resolve", "summary": "Resolve a hosted connect link token for the public connect page.", "tags": [ "connect" ], "security": [], "responses": { "200": { "description": "OK" } } } }, "/connect/begin": { "post": { "operationId": "connect_begin", "summary": "Begin a hosted OAuth connection using a connect-link token.", "tags": [ "connect" ], "security": [], "responses": { "200": { "description": "OK" } } } }, "/v1/posts": { "post": { "operationId": "posts_create", "summary": "Create, schedule, or save a post as a draft for one or more platforms.", "tags": [ "posts" ], "x-required-scope": "posts:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostBody" } } } }, "responses": { "200": { "description": "Created. status may be 'pending_approval' (held for review by the project's agent policy) with zero legs." }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Scope or account allowlist blocked (DY_KEY_*)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "422": { "description": "Pre-flight validation failed (violations[])", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "429": { "description": "Key posts-per-day cap reached (DY_KEY_POST_CAP_EXCEEDED)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "get": { "operationId": "posts_list", "summary": "List posts in a project.", "tags": [ "posts" ], "x-required-scope": "posts:read", "responses": { "200": { "description": "Posts (query: projectId, status?, limit?, cursor?)" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}": { "get": { "operationId": "posts_get", "summary": "Get a post and its per-platform delivery legs.", "tags": [ "posts" ], "x-required-scope": "posts:read", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detail with legs[]" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "patch": { "operationId": "posts_update", "summary": "Update a draft body or reschedule a scheduled post.", "tags": [ "posts" ], "x-required-scope": "posts:write", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Edit a draft ({text}) or reschedule ({scheduledFor}).", "responses": { "200": { "description": "Updated" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "409": { "description": "Wrong state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "delete": { "operationId": "posts_delete", "summary": "Cancel a post that has not been published.", "tags": [ "posts" ], "x-required-scope": "posts:write", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/analytics": { "get": { "operationId": "posts_get_analytics", "summary": "Get analytics snapshots for a post.", "tags": [ "posts" ], "x-required-scope": "analytics:read", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/boost": { "post": { "operationId": "posts_boost", "summary": "Create a paid promotion for a published post.", "tags": [ "posts" ], "x-idempotency-key": "supported", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Paid promotion; requires ads:boost (or legacy ads:write). Honors the Idempotency-Key header: 409 while the first attempt runs, replay within the completion window returns the original response.", "responses": { "200": { "description": "Boost created" }, "400": { "description": "Ceiling or validation blocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Scope missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/legs/{legId}/retry": { "post": { "operationId": "posts_retry_leg", "summary": "Retry one failed delivery leg without duplicating the platform post.", "tags": [ "posts" ], "x-required-scope": "posts:write", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "legId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Leg re-fired" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "404": { "description": "No such leg on this post", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "409": { "description": "Leg not in failed state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/retry": { "post": { "operationId": "posts_retry", "summary": "Retry every failed delivery leg on a post.", "tags": [ "posts" ], "x-required-scope": "posts:write", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/legs": { "get": { "operationId": "posts_list_legs", "summary": "List the per-platform delivery legs for a post.", "tags": [ "posts" ], "x-required-scope": "posts:read", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/boosts": { "get": { "operationId": "posts_list_boosts", "summary": "List paid promotions created for a post.", "tags": [ "posts" ], "x-required-scope": "analytics:read", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the analytics:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/duplicate": { "post": { "operationId": "posts_duplicate", "summary": "Copy a post body into a new unscheduled draft.", "tags": [ "posts" ], "x-required-scope": "posts:write", "x-idempotency-key": "supported", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/queue/slots": { "get": { "operationId": "queue_get_slots", "summary": "Get the weekly posting slots for a project.", "tags": [ "queue" ], "x-required-scope": "posts:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "put": { "operationId": "queue_set_slots", "summary": "Replace the weekly posting slots for a project.", "tags": [ "queue" ], "x-required-scope": "posts:write", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/queue/next-slot": { "get": { "operationId": "queue_next_slot", "summary": "Get the next free posting slot for a project.", "tags": [ "queue" ], "x-required-scope": "posts:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/queue/preview": { "get": { "operationId": "queue_preview", "summary": "Preview upcoming free posting slots for a project.", "tags": [ "queue" ], "x-required-scope": "posts:read", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:read scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/move-to-drafts": { "post": { "operationId": "posts_move_to_drafts", "summary": "Move a failed post back to drafts for editing.", "tags": [ "posts" ], "x-required-scope": "posts:write", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Now a draft" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "409": { "description": "Not draftable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/submit": { "post": { "operationId": "posts_submit", "summary": "Submit a draft for approval.", "tags": [ "posts" ], "x-required-scope": "posts:write", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/approve": { "post": { "operationId": "posts_approve", "summary": "Approve a pending post and begin or schedule publishing.", "tags": [ "posts" ], "x-required-scope": "posts:write", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/posts/{postId}/reject": { "post": { "operationId": "posts_reject", "summary": "Reject a pending post with a reason.", "tags": [ "posts" ], "x-required-scope": "posts:write", "parameters": [ { "name": "postId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the posts:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/media": { "post": { "operationId": "media_upload", "summary": "Upload a small media file as raw request bytes.", "tags": [ "media" ], "description": "Direct upload (< 15MB); use /v1/media/presign above that.", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "get": { "operationId": "media_list", "summary": "List media owned by the organization.", "tags": [ "media" ], "x-required-scope": "media:write", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the media:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/media/ingest-url": { "post": { "operationId": "media_ingest_url", "summary": "Fetch a remote media URL into managed storage.", "tags": [ "media" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/media/presign": { "post": { "operationId": "media_presign", "summary": "Create a presigned upload URL for a large media file.", "tags": [ "media" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/media/{id}/finalize": { "post": { "operationId": "media_finalize", "summary": "Finalize a completed presigned media upload.", "tags": [ "media" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/media/{id}": { "get": { "operationId": "media_get", "summary": "Get media metadata and processing status.", "tags": [ "media" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "delete": { "operationId": "media_delete", "summary": "Delete an unreferenced media item.", "tags": [ "media" ], "x-required-scope": "media:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "403": { "description": "Missing the media:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/interactions": { "get": { "operationId": "interactions_list", "summary": "List the unified interaction inbox with optional filters.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/interactions/{id}/reply": { "post": { "operationId": "interactions_reply", "summary": "Reply to an inbound interaction through its platform connector.", "tags": [ "inbox" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/interactions/{id}/assign": { "post": { "operationId": "interactions_assign", "summary": "Assign an interaction to an organization member.", "tags": [ "inbox" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/interactions/{id}": { "get": { "operationId": "interactions_get", "summary": "Get one inbox interaction.", "tags": [ "inbox" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/interactions/{id}/read": { "post": { "operationId": "interactions_mark_read", "summary": "Mark an interaction as read.", "tags": [ "inbox" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/interactions/{id}/resolve": { "post": { "operationId": "interactions_resolve", "summary": "Resolve an interaction.", "tags": [ "inbox" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/interactions/{id}/private-reply": { "post": { "operationId": "interactions_private_reply", "summary": "Send the platform-limited private reply for a comment.", "tags": [ "inbox" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/inbox/comments": { "get": { "operationId": "inbox_comments_list", "summary": "List comment interactions.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/inbox/mentions": { "get": { "operationId": "inbox_mentions_list", "summary": "List mention interactions.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/inbox/reviews": { "get": { "operationId": "inbox_reviews_list", "summary": "List review interactions.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/inbox/conversations": { "get": { "operationId": "conversations_list", "summary": "List direct-message conversations.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/inbox/conversations/{id}": { "get": { "operationId": "conversations_get", "summary": "Get one direct-message conversation.", "tags": [ "inbox" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/inbox/conversations/{id}/messages": { "get": { "operationId": "conversation_messages_list", "summary": "List messages in a conversation.", "tags": [ "inbox" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "post": { "operationId": "conversation_messages_send", "summary": "Send a direct message in an open conversation window.", "tags": [ "inbox" ], "x-idempotency-key": "supported", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/auto-reply-rules": { "get": { "operationId": "auto_reply_rules_list", "summary": "List auto-reply rules.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "post": { "operationId": "auto_reply_rules_create", "summary": "Create an auto-reply rule.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/auto-reply-rules/{id}": { "patch": { "operationId": "auto_reply_rules_update", "summary": "Update an auto-reply rule.", "tags": [ "inbox" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "delete": { "operationId": "auto_reply_rules_delete", "summary": "Delete an auto-reply rule.", "tags": [ "inbox" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/campaigns": { "post": { "operationId": "campaigns_create", "summary": "Create an advertising campaign with a spend ceiling.", "tags": [ "campaigns" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/campaigns/{id}": { "get": { "operationId": "campaigns_get", "summary": "Get one campaign.", "tags": [ "campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/campaigns/{id}/report": { "get": { "operationId": "campaigns_report", "summary": "Get a campaign rollup report.", "tags": [ "campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/webhooks": { "post": { "operationId": "webhooks_create", "summary": "Register an outbound webhook endpoint.", "tags": [ "webhooks" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "get": { "operationId": "webhooks_list", "summary": "List outbound webhook endpoints.", "tags": [ "webhooks" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/webhooks/{id}": { "delete": { "operationId": "webhooks_delete", "summary": "Delete an outbound webhook endpoint.", "tags": [ "webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "patch": { "operationId": "webhooks_update", "summary": "Update an outbound webhook endpoint.", "tags": [ "webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "operationId": "webhooks_rotate_secret", "summary": "Rotate a webhook signing secret.", "tags": [ "webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "webhooks_test_fire", "summary": "Send a test event to a webhook endpoint.", "tags": [ "webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/webhooks/events": { "get": { "operationId": "webhook_events_list", "summary": "List supported outbound webhook event types.", "tags": [ "webhooks" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/api-keys": { "get": { "operationId": "api_keys_list", "summary": "List active API keys.", "tags": [ "api-keys" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "post": { "operationId": "api_keys_create", "summary": "Create an API key.", "tags": [ "api-keys" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/api-keys/{id}": { "delete": { "operationId": "api_keys_delete", "summary": "Revoke an API key.", "tags": [ "api-keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "patch": { "operationId": "api_keys_update", "summary": "Update an API key and its policy.", "tags": [ "api-keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/webhooks/deliveries": { "get": { "operationId": "webhook_deliveries_list", "summary": "List outbound webhook delivery attempts.", "tags": [ "webhooks" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }, "/v1/webhooks/deliveries/{id}/replay": { "post": { "operationId": "webhook_deliveries_replay", "summary": "Replay an outbound webhook delivery.", "tags": [ "webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } } } }