{ "openapi": "3.1.0", "info": { "title": "Sociamonials API", "version": "1.2.0", "description": "Import in ChatGPT: create a GPT, Configure, Actions, Import from file. Authentication: API Key with Auth Type Bearer \u2014 paste your API key as the value and it travels as the Authorization header. Create a key at https://www.sociamonials.com/login.php?redirect=accounts%2Fapi_keys.php (sign in first, then Create API Key). Try GET /api/v1/me first: it reports exactly what this key may do. Descriptions here are shortened to the importer limit; the full field reference \u2014 including the agency provisioning endpoints left out to stay under the ~30 operation cap \u2014 is at https://www.sociamonials.com/developers.php." }, "servers": [ { "url": "https://www.sociamonials.com" } ], "x-error-catalog": { "missing_credentials": "No Authorization header was sent. (401)", "credentials_in_query_string": "The credential was sent in the query string. Send it in the Authorization header only. (401)", "invalid_credentials": "The credential is unknown, revoked or expired - the three are deliberately indistinguishable. (401)", "api_subscription_inactive": "API access is not active for this account (free trial, or account suspended). The code name is retained for contract compatibility. (402)", "api_access_disabled": "API access is temporarily disabled platform-wide by the administrator. Retry later. (503)", "rate_limited": "Too many requests for this credential. Retry-After tells you when to retry. (429)", "api_write_operations_disabled": "An administrator has disabled API write operations; reads still work. (403)", "permission_denied": "The API Agent lacks the permission this operation requires. (403)", "workspace_access_denied": "The permission this operation requires is not granted in that workspace. (403)", "profile_not_assigned": "A requested social profile is not assigned to this API Agent. The most common integration failure - list the profiles first and use only those with agent_can_publish_to true. (403)", "attached_user_no_reports_permission": "The credential is attached to a sub-user who lacks the \"Access Reports\" permission that analytics requires. (403)", "validation_failed": "One or more fields are invalid; error.errors maps each field to its problem. (422)", "workspace_required": "The credential could not be matched to a workspace. Pass workspace_registration_id to name the workspace this call should act on. (422)", "unsupported_campaign_type": "The campaign is not a V2 Viral Sweepstakes; only V2 sweepstakes are supported. (422)", "not_found": "No such record is visible to this credential. Also returned instead of 403 where confirming existence would leak information. On the id-constrained routes it can arrive BEFORE the controller runs - a non-numeric id (GET /api/v1/posts/abc/analytics) matches no route, so the 404 comes back without the record ever being looked up. (404)", "cannot_cancel": "The post cannot be canceled - typically it is already delivered. (409)", "idempotency_in_flight": "An earlier request with the same Idempotency-Key is still running. Retry shortly. (409)", "method_not_allowed": "That HTTP method is not supported on this endpoint. Check the verb against the operation. (405)", "internal_error": "An unexpected server error. The envelope never contains the exception message or a stack trace, so error.request_id is the only handle: quote it to support. (500)", "http_error": "Generic fallback for any other HTTP error status the framework raises. Rare - treat it as the default branch of your error handling and read the HTTP status. (4xx/5xx)" }, "x-error-code-status": { "missing_credentials": 401, "credentials_in_query_string": 401, "invalid_credentials": 401, "api_subscription_inactive": 402, "api_access_disabled": 503, "rate_limited": 429, "api_write_operations_disabled": 403, "permission_denied": 403, "workspace_access_denied": 403, "profile_not_assigned": 403, "attached_user_no_reports_permission": 403, "not_found": 404, "method_not_allowed": 405, "cannot_cancel": 409, "idempotency_in_flight": 409, "validation_failed": 422, "workspace_required": 422, "unsupported_campaign_type": 422, "internal_error": 500 }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer . Credentials are issued per API Agent and sent only in this header \u2014 never in the query string." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } }, "security": [ { "bearer": [] } ], "tags": [ { "name": "Identity" }, { "name": "Workspaces & Profiles" }, { "name": "Publishing" }, { "name": "Viral Sweepstakes" }, { "name": "Analytics" }, { "name": "MCP" } ], "paths": { "/api/v1/me": { "get": { "summary": "Who am I", "description": "Identity, credential metadata, entitlement state and the full per-workspace permission map for the authenticated API Agent. Call this first \u2014 it answers every \"am I allowed to\u2026\" question.", "tags": [ "Identity" ], "x-permission": "none \u2014 any active credential", "responses": { "200": { "description": "Identity", "content": { "application/json": { "example": { "agent": { "id": 2, "type": "workspace", "product_label": "Workspace API Agent", "name": "Realty Agent", "status": "active" }, "credential": { "name": "my-credential", "token_prefix": "sm_agent_XXXXXXX", "expires_at": null }, "entitlement": { "state": "active", "source": "account_plan", "source_label": "Included with your plan" }, "workspaces": { "123456": { "workspace_name": "Realty Client", "permissions": { "posts.read": true, "posts.create": true, "sweepstakes.create": true } } } } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "x-discovery": [ "Call this first. The workspaces map it returns lists every workspace_registration_id this credential can use and the permissions it holds there." ], "operationId": "getMe", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "exempt", "x-rate-cost": "not counted", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials" ] } }, "/api/v1/workspaces": { "get": { "summary": "List assigned workspaces", "description": "Every workspace this API Agent can operate in, each with its effective permission map and whether posting routes through approval.", "tags": [ "Workspaces & Profiles" ], "x-permission": "none \u2014 any active credential", "responses": { "200": { "description": "Workspaces", "content": { "application/json": { "example": { "workspaces": [ { "workspace_registration_id": 123456, "name": "client-workspace", "company": "Client Co", "display_name": "Client Co", "permissions": { "posts.create": true }, "requires_approval_for_posting": false } ] } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "x-discovery": [ "workspace_registration_id values used by every other endpoint come from here." ], "operationId": "listWorkspaces", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "exempt", "x-rate-cost": "not counted", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials" ] } }, "/api/v1/workspaces/{workspaceId}/social-profiles": { "get": { "summary": "List social profiles", "description": "Connected social profiles in a workspace with per-profile publish authorization for this agent. No tokens are ever returned.", "tags": [ "Workspaces & Profiles" ], "x-permission": "profiles.read", "responses": { "200": { "description": "Profiles", "content": { "application/json": { "example": { "workspace_registration_id": 123456, "profiles": [ { "network": "fb", "network_name": "Facebook", "profile_ref": "YOUR_PROFILE_ID", "name": "My Page", "agent_can_publish_to": true } ] } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Workspace registration id (GET /api/v1/workspaces)", "schema": { "type": "integer" } } ], "x-discovery": [ "workspaceId \u2190 GET /api/v1/workspaces", "profile_ref values for POST /api/v1/posts networks.*.profile_refs come from here \u2014 use only profiles where agent_can_publish_to is true." ], "operationId": "listSocialProfiles", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "exempt", "x-rate-cost": "not counted", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "workspace_access_denied" ] } }, "/api/v1/posts": { "post": { "summary": "Create a post (draft, scheduled, or publish now)", "description": "Creates one post across one or more networks. mode=draft saves without publishing anything; mode=queue adds it to your posting queue. Name-based options (category, watermark, hashtag_group, cta_group, post_preset ...", "tags": [ "Publishing" ], "x-permission": "posts.create (drafts) + posts.schedule (scheduled / publish_now)", "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "post_id": 9001, "status": "draft", "requires_approval": false, "warnings": [] } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed \u2014 error.errors maps each field to its problem", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer", "description": "Workspace agents: omit \u2014 the workspace is inferred from the credential. Agency agents: required \u2014 pass the target workspace_registration_id (list them with GET /api/v1/workspaces).", "x-omit-ok": true }, "mode": { "type": "string", "description": "What happens after the post is created. 'draft' saves it without scheduling (nothing ever publishes). 'queue' adds it to your posting queue and the queue schedule picks the send time (same as leaving the schedule columns blank in a CSV import). 'scheduled' sends at publish_at. 'publish_now' sends immediately.", "enum": [ "draft", "queue", "scheduled", "publish_now" ] }, "message": { "type": "string", "description": "The text of your post. Optional when image_urls or video_url is provided \u2014 a post needs at least one of message, image_urls, or video_url; empty values are ignored. Character limits per network: Facebook 63,206 \u00b7 X/Twitter 280 \u00b7 LinkedIn 3,000 \u00b7 Instagram 2,200 \u00b7 Pinterest 500 \u00b7 Google Business Profile 1,500 \u00b7 Threads 500 \u00b7 TikTok 150 \u00b7 Bluesky 300.", "x-omit-ok": true }, "networks": { "type": "object", "description": "Keyed by network code; at least one network is required unless post_preset supplies saved profiles (those replace anything passed here). Network codes, in canonical order: fb Facebook, tw X/Twitter, ln LinkedIn, in Instagram, pi Pinterest, gmb Google Business, thrd Threads, tiktok TikTok, yt YouTube, blsk Bluesky. Text limits: tw 280, pi 500, gmb 1500, thrd 500, blsk 300 characters. in/tiktok require an image or video; yt requires a video; pi requires a board (networks.pi.board_name or board_id). Do not confuse the two.", "additionalProperties": { "type": "object", "required": [ "profile_refs" ], "properties": { "profile_refs": { "type": "array", "items": { "type": "string" }, "description": "profile_ref values from GET /api/v1/workspaces/{workspaceId}/social-profiles. Every profile must be assigned to your API Agent." }, "message": { "type": "string", "description": "Optional per-network override of the top-level message.", "x-omit-ok": true } } }, "x-omit-ok": true }, "publish_at": { "type": "string", "description": "When to send, as an ISO-8601 UTC timestamp. Required when mode=scheduled.", "format": "date-time", "x-omit-ok": true }, "randomize_minute": { "type": "boolean", "description": "Scheduled posts only: randomize the minute of the send time so posting looks less automated (the CSV \"Random\" minute).", "default": false }, "link": { "type": "string", "description": "A single website URL to attach to your post. If you also attach a photo or video, the link is added to the end of your message. On X/Twitter the URL counts against the 280-character limit.", "x-omit-ok": true }, "image_urls": { "type": "array", "items": { "type": "string" }, "description": "Direct https URLs of your image(s); multiple images make a carousel. A single URL string is accepted, and image_url (singular) is accepted as an alias. The URL must be publicly accessible \u2014 a Google Drive or other password-protected link will fail. Do not combine with video_url \u2014 the upload fails.", "x-omit-ok": true }, "video_url": { "type": "string", "description": "Direct https URL of your .mp4 video FILE (a YouTube page URL will not work \u2014 the URL should end in .mp4). The URL must be publicly accessible \u2014 a Google Drive or other password-protected link will fail. Do not combine with image_urls \u2014 the upload fails.", "x-omit-ok": true }, "video_thumbnail_url": { "type": "string", "description": "Optional thumbnail image for your video (video posts only). Supported by Facebook, Instagram, Pinterest, LinkedIn and Google Business Profile. .jpg or .png only (no .webp). The URL must be publicly accessible \u2014 a Google Drive or other password-protected link will fail.", "x-omit-ok": true }, "alt_text": { "type": "string", "description": "Accessibility alt-text applied to every attached image. Instagram and Google Business Profile do not support alt-text.", "x-omit-ok": true }, "first_comment": { "type": "string", "description": "Posted as the first comment under your post on Facebook, Instagram, LinkedIn, Bluesky and Threads.", "x-omit-ok": true }, "story": { "type": "boolean", "description": "true posts your image/video as a Story on your Facebook and Instagram profiles. Needs exactly one image or one video.", "default": false }, "category": { "type": "string", "description": "The name of a saved Category to assign the post to (as shown in your Categories list). Unknown names are reported in warnings and skipped.", "x-omit-ok": true }, "watermark": { "type": "string", "description": "Add a stored watermark to the image(s) in your post. Use 'Default' for your default watermark or the exact name of a saved watermark. Watermarks are not applied to videos.", "x-omit-ok": true }, "hashtag_group": { "type": "string", "description": "The exact name of a saved Hashtag Group. Hashtags are randomly picked from the group and inserted after the message and link (or into the first comment, when the group is configured that way).", "x-omit-ok": true }, "cta_group": { "type": "string", "description": "The exact name of a saved Call-to-Action Group (or 'Default'). One CTA is randomly picked per network and inserted after the message and link. If the CTA already contains a link, consider omitting the link field or your post will contain two links.", "x-omit-ok": true }, "post_preset": { "type": "string", "description": "The exact name of a saved Post Preset, or 'default' for the workspace's default preset. Applies the preset's saved settings (approval hold, category, team note; fields you pass explicitly win) AND, when the preset has saved social profiles, the profiles themselves: they define the selection, replacing anything passed in networks..profile_refs (per-network message overrides are kept), and networks may be omitted entirely. Your API Agent must be permitted on every preset profile. Unknown preset names are reported in warnings and your explicit networks are used.", "x-omit-ok": true }, "team_note": { "type": "string", "description": "An internal Team Comment on the post (never published). Team members can reply \u2014 useful for Canva template links or instructions.", "x-omit-ok": true }, "pinterest": { "type": "object", "description": "Pinterest-only options (network code pi). Canonical form: nest these under networks.pi (e.g. networks.pi.board_id); this top-level object remains accepted for backward compatibility (nested values win).", "properties": { "pin_title": { "type": "string", "description": "The Pinterest Pin Title shown above the pin. Optional.", "x-omit-ok": true }, "board_name": { "type": "string", "description": "The name of the Pinterest board to post to, exactly as shown in Pinterest. Easiest option \u2014 the API looks up the board on the selected Pinterest profile.", "x-omit-ok": true }, "board_id": { "type": "string", "description": "Advanced alternative to board_name: the internal board id.", "x-omit-ok": true } }, "x-omit-ok": true }, "tiktok": { "type": "object", "description": "TikTok-only options (network code tiktok). Canonical form: nest these under networks.tiktok; this top-level object remains accepted for backward compatibility (nested values win).", "properties": { "carousel_title": { "type": "string", "description": "Title for a TikTok image-carousel post (ignored for videos). Defaults to the beginning of your message.", "x-omit-ok": true }, "visibility": { "type": "string", "description": "Who can see the post. Defaults to 'public'.", "enum": [ "public", "private", "friends", "followers" ], "default": "public" }, "allow_comments": { "type": "boolean", "description": "Allow comments on the post. Default true.", "default": true }, "allow_duet": { "type": "boolean", "description": "Allow others to Duet the post. Default true.", "default": true }, "allow_stitch": { "type": "boolean", "description": "Allow others to Stitch the post. Default true.", "default": true }, "ai_generated_content": { "type": "boolean", "description": "Tell TikTok the post contains realistic AI-generated content. Default false.", "default": false }, "promotes_your_brand": { "type": "boolean", "description": "The post promotes your own brand, product or service. Default false.", "default": false }, "branded_content": { "type": "boolean", "description": "The post promotes another brand as part of a paid partnership or sponsorship. Default false.", "default": false } }, "x-omit-ok": true }, "youtube": { "type": "object", "description": "YouTube-only options (network code yt). Canonical form: nest these under networks.yt (e.g. networks.yt.title); this top-level object remains accepted for backward compatibility (nested values win).", "properties": { "title": { "type": "string", "description": "The YouTube video title (max 100 characters). Defaults to the beginning of your message.", "x-omit-ok": true }, "description": { "type": "string", "description": "The YouTube video description.", "x-omit-ok": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "YouTube video tags \u2014 the same Video Tags field as the Publisher. Pass an array of tag strings (a single comma-separated string is also accepted).", "x-omit-ok": true }, "visibility": { "type": "string", "description": "Video visibility. Defaults to 'public'.", "enum": [ "public", "private", "unlisted" ], "default": "public" }, "notify_subscribers": { "type": "boolean", "description": "Notify your subscribers when the video is published. Default true.", "default": true }, "made_for_kids": { "type": "boolean", "description": "Set true only if children are the primary audience. Default false.", "default": false }, "synthetic_media": { "type": "boolean", "description": "The video contains realistic AI-generated or altered content. Default false.", "default": false } }, "x-omit-ok": true }, "validate_only": { "type": "boolean", "description": "Sandbox dry run: the full validation pipeline runs (permissions, profile grants, selection resolution, platform rules, limits) and NOTHING is created. Response reports valid, profile_resolution and warnings. Errors are the same 403/422 a real request would produce. Idempotency keys are ignored on dry runs.", "default": false }, "strict": { "type": "boolean", "description": "Default false: forgiving, warning-based behaviour. true converts profile-selection conflicts, unknown or missing presets, unknown networks, and no-eligible-default-profile cases into 422 validation_failed responses (with field, workspace, and network identified). In multi-workspace publishing a strict failure creates nothing. Authorization is identical in both modes.", "default": false }, "idempotency_key": { "type": "string", "description": "Safe-retry key; also accepted as an Idempotency-Key header. Replays return the ORIGINAL stored result \u2014 including profile_resolution \u2014 and never re-resolve defaults that changed after the first request.", "x-omit-ok": true } }, "required": [ "mode" ] }, "example": { "mode": "draft", "message": "Hello from the API!", "networks": { "fb": { "profile_refs": [ "YOUR_PROFILE_ID" ] } } } } } }, "x-network-groups": { "per_network_property_names": [ "pinterest", "tiktok", "youtube" ], "shared_fields": [ { "name": "profile_refs", "type": "array", "required": true, "description": "profile_ref values from GET /api/v1/workspaces/{workspaceId}/social-profiles. Every profile must be assigned to your API Agent." }, { "name": "message", "type": "string", "required": false, "description": "Optional per-network override of the top-level message.", "x-omit-ok": true } ], "networks": { "fb": { "code": "fb", "name": "Facebook", "nuance": "Set story=true to post a single image or video as a Facebook Story (needs exactly one). Supports first_comment, alt_text and video_thumbnail_url. Text limit 63,206 characters.", "fields": [] }, "tw": { "code": "tw", "name": "X/Twitter", "nuance": "A link counts against the 280-character limit. No first_comment. One post per call \u2014 reply threads are not created.", "fields": [] }, "ln": { "code": "ln", "name": "LinkedIn", "nuance": "Supports first_comment and video_thumbnail_url. Text limit 3,000 characters.", "fields": [] }, "in": { "code": "in", "name": "Instagram", "nuance": "Requires an image or a video \u2014 a text-only post is rejected. Set story=true to post a Story (exactly one image or video). Supports first_comment. alt_text is NOT applied on Instagram. Text limit 2,200 characters.", "fields": [] }, "pi": { "code": "pi", "name": "Pinterest", "nuance": "Requires a board: set networks.pi.board_name (easiest) or board_id. pin_title is optional. Supports video_thumbnail_url. Text limit 500 characters.", "fields": [ { "name": "pin_title", "type": "string", "required": false, "description": "The Pinterest Pin Title shown above the pin. Optional.", "x-omit-ok": true }, { "name": "board_name", "type": "string", "required": false, "description": "The name of the Pinterest board to post to, exactly as shown in Pinterest. Easiest option \u2014 the API looks up the board on the selected Pinterest profile.", "x-omit-ok": true }, { "name": "board_id", "type": "string", "required": false, "description": "Advanced alternative to board_name: the internal board id.", "x-omit-ok": true } ], "option_object": "pinterest" }, "gmb": { "code": "gmb", "name": "Google Business", "nuance": "alt_text is NOT applied on Google Business Profile. Supports video_thumbnail_url. Text limit 1,500 characters.", "fields": [] }, "thrd": { "code": "thrd", "name": "Threads", "nuance": "Supports first_comment. Text limit 500 characters.", "fields": [] }, "tiktok": { "code": "tiktok", "name": "TikTok", "nuance": "Requires an image or a video. carousel_title titles an image-carousel post. visibility, allow_comments, allow_duet and allow_stitch control the post; ai_generated_content, promotes_your_brand and branded_content set the required content disclosures. Message limit 150 characters.", "fields": [ { "name": "carousel_title", "type": "string", "required": false, "description": "Title for a TikTok image-carousel post (ignored for videos). Defaults to the beginning of your message.", "x-omit-ok": true }, { "name": "visibility", "type": "string", "required": false, "description": "Who can see the post. Defaults to 'public'.", "enum": [ "public", "private", "friends", "followers" ], "default": "public" }, { "name": "allow_comments", "type": "boolean", "required": false, "description": "Allow comments on the post. Default true.", "default": true }, { "name": "allow_duet", "type": "boolean", "required": false, "description": "Allow others to Duet the post. Default true.", "default": true }, { "name": "allow_stitch", "type": "boolean", "required": false, "description": "Allow others to Stitch the post. Default true.", "default": true }, { "name": "ai_generated_content", "type": "boolean", "required": false, "description": "Tell TikTok the post contains realistic AI-generated content. Default false.", "default": false }, { "name": "promotes_your_brand", "type": "boolean", "required": false, "description": "The post promotes your own brand, product or service. Default false.", "default": false }, { "name": "branded_content", "type": "boolean", "required": false, "description": "The post promotes another brand as part of a paid partnership or sponsorship. Default false.", "default": false } ], "option_object": "tiktok" }, "yt": { "code": "yt", "name": "YouTube", "nuance": "Requires a video (video_url ending in .mp4). title (max 100), description and tags map to the YouTube fields; visibility is public, private or unlisted; notify_subscribers, made_for_kids and synthetic_media are the publish flags.", "fields": [ { "name": "title", "type": "string", "required": false, "description": "The YouTube video title (max 100 characters). Defaults to the beginning of your message.", "x-omit-ok": true }, { "name": "description", "type": "string", "required": false, "description": "The YouTube video description.", "x-omit-ok": true }, { "name": "tags", "type": "array", "required": false, "description": "YouTube video tags \u2014 the same Video Tags field as the Publisher. Pass an array of tag strings (a single comma-separated string is also accepted).", "x-omit-ok": true }, { "name": "visibility", "type": "string", "required": false, "description": "Video visibility. Defaults to 'public'.", "enum": [ "public", "private", "unlisted" ], "default": "public" }, { "name": "notify_subscribers", "type": "boolean", "required": false, "description": "Notify your subscribers when the video is published. Default true.", "default": true }, { "name": "made_for_kids", "type": "boolean", "required": false, "description": "Set true only if children are the primary audience. Default false.", "default": false }, { "name": "synthetic_media", "type": "boolean", "required": false, "description": "The video contains realistic AI-generated or altered content. Default false.", "default": false } ], "option_object": "youtube" }, "blsk": { "code": "blsk", "name": "Bluesky", "nuance": "Supports first_comment. Text limit 300 characters.", "fields": [] } } }, "x-discovery": [ "profile_refs \u2190 GET /api/v1/workspaces/{workspaceId}/social-profiles", "workspace_registration_id \u2190 GET /api/v1/workspaces (agency agents only; workspace agents omit it)" ], "operationId": "createPost", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "creates a post (draft, queued, scheduled, or publish_now per mode)", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "credentials_in_query_string", "http_error", "idempotency_in_flight", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "permission_denied", "profile_not_assigned", "rate_limited", "validation_failed" ] } }, "/api/v1/posts/{id}": { "get": { "summary": "Get a post", "description": "Full status of one post: draft/approved/delivered flags and per-network delivery. Each network reports delivery_status \u2014 pending (not yet attempted), processing (accepted and queued with the network, e.g. ...", "tags": [ "Publishing" ], "x-permission": "posts.read", "responses": { "200": { "description": "Post", "content": { "application/json": { "example": { "post_id": 9001, "workspace_registration_id": 123456, "message": "Hello\u2026", "publish_date_utc": "2026-07-12 18:00:00", "draft": false, "canceled": false, "approved": true, "delivered": false, "networks": { "fb": { "enabled": true, "delivered": false, "delivery_status": "processing", "error": null }, "tw": { "enabled": true, "delivered": false, "delivery_status": "failed", "error": "Invalid or expired token" } } } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "post_id returned by POST /api/v1/posts", "schema": { "type": "integer" } } ], "x-discovery": [ "id \u2190 the post_id returned by POST /api/v1/posts" ], "operationId": "getPost", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "rate_limited" ] }, "delete": { "summary": "Cancel a scheduled post", "description": "Non-destructive cancel; already-delivered posts cannot be canceled (409).", "tags": [ "Publishing" ], "x-permission": "posts.cancel", "responses": { "200": { "description": "Canceled", "content": { "application/json": { "example": { "post_id": 9001, "status": "canceled" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "post_id to cancel", "schema": { "type": "integer" } } ], "x-discovery": [ "id \u2190 the post_id returned by POST /api/v1/posts" ], "operationId": "cancelPost", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "cancels an undelivered post (non-destructive stop flag)", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "cannot_cancel", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "rate_limited" ] } }, "/api/v1/workspaces/{workspaceId}/analytics": { "get": { "summary": "Workspace analytics", "description": "Delivery metrics for one workspace over a UTC window (default: last 30 days). totals is a disjoint lifecycle partition (delivered/pending/drafts/canceled always sum to created); by_network reports targeted vs platform-CONFIRMED delivered for all 10 networks. ...", "tags": [ "Analytics" ], "x-permission": "analytics.read", "responses": { "200": { "description": "Metrics", "content": { "application/json": { "example": { "workspace_registration_id": 123456, "window": { "from_utc": "2026-06-12 00:00:00", "to_utc": "2026-07-12 00:00:00", "timezone": "UTC" }, "totals": { "posts_created": 57, "posts_delivered": 9, "posts_pending": 14, "drafts": 28, "canceled": 6 }, "by_network": { "fb": { "network_name": "Facebook", "posts_targeted": 21, "posts_delivered": 3 }, "\u2026": "\u2026" }, "meta": { "metric_definitions": { "\u2026": "\u2026" }, "timezone": "UTC" } } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed \u2014 error.errors maps each field to its problem", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Workspace registration id", "schema": { "type": "integer" } }, { "name": "from_utc", "in": "query", "required": false, "description": "ISO-8601 UTC start (default: 30 days ago)", "schema": { "type": "string" } }, { "name": "to_utc", "in": "query", "required": false, "description": "ISO-8601 UTC end (default: now)", "schema": { "type": "string" } } ], "x-discovery": [ "workspaceId \u2190 GET /api/v1/workspaces" ], "operationId": "getWorkspaceAnalytics", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "attached_user_no_reports_permission", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "rate_limited", "validation_failed", "workspace_access_denied" ] } }, "/api/v1/workspaces/{workspaceId}/published-messages": { "get": { "summary": "Published Messages report", "description": "The in-app Reports > Posts screen as an API: one row per PUBLISHED message with the same columns - publisher, published_at_utc, message, per-network targeting flags (compose-time selection, not delivery), links, clicks, gbp_clicks, leads, sales, revenue (numeric USD), likes, comments ...", "tags": [ "Analytics" ], "x-permission": "analytics.read", "responses": { "200": { "description": "Report", "content": { "application/json": { "example": { "workspace_registration_id": 123456, "window": { "from_utc": "2026-06-28 00:00:00", "to_utc": "2026-07-28 00:00:00", "timezone": "UTC", "all_dates": false }, "filters": { "networks": [ "facebook", "instagram" ], "category_id": null, "post_id": null }, "total": 24, "messages": [ { "post_id": 9001, "published_by": "jane.smith", "published_at_utc": "2026-07-05 17:02:00", "message": "Have you tried our new tool?", "networks": { "facebook": 1, "twitter": 1, "\u2026": "\u2026" }, "links": [ "https://www.example.com" ], "clicks": 42, "gbp_clicks": 3, "leads": 2, "sales": 1, "revenue": 99, "currency": "USD", "likes": 17, "comments": 4, "custom_conversions": [ { "event": "c1", "name": "", "count": 1 } ] } ], "meta": { "\u2026": "\u2026" } } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed \u2014 error.errors maps each field to its problem", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Workspace registration id", "schema": { "type": "integer" } }, { "name": "date_range", "in": "query", "required": false, "description": "The screen presets; ignored when from_utc/to_utc are sent", "schema": { "type": "string", "enum": [ "all", "last_30_days", "last_60_days", "last_90_days" ], "default": "last_30_days" } }, { "name": "from_utc", "in": "query", "required": false, "description": "ISO-8601 UTC start (Custom Range)", "schema": { "type": "string" } }, { "name": "to_utc", "in": "query", "required": false, "description": "ISO-8601 UTC end (Custom Range)", "schema": { "type": "string" } }, { "name": "networks", "in": "query", "required": false, "description": "comma list of facebook,linkedin,twitter,youtube,instagram,bluesky,gbp,pinterest,tiktok,threads - omitted = all ten (the screen default)", "schema": { "type": "string" } }, { "name": "post_id", "in": "query", "required": false, "description": "restrict to one message", "schema": { "type": "integer" } }, { "name": "category_id", "in": "query", "required": false, "description": "the screen's Categories dropdown (post category id)", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "x-discovery": [ "workspaceId \u2190 GET /api/v1/workspaces", "post_id \u2190 a post_id from POST /api/v1/posts, or from the messages[] rows this endpoint returns" ], "operationId": "getPublishedMessages", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "attached_user_no_reports_permission", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "rate_limited", "validation_failed", "workspace_access_denied" ] } }, "/api/v1/workspaces/{workspaceId}/campaigns-report": { "get": { "summary": "Campaigns report", "description": "The in-app Reports > Campaigns screen as an API, covering EVERY campaign product - viral sweepstakes, contests, testimonials, galleries, landing pages, refer-a-friend - one row per campaign. ...", "tags": [ "Analytics" ], "x-permission": "analytics.read", "responses": { "200": { "description": "Report", "content": { "application/json": { "example": { "workspace_registration_id": 123456, "window": { "from_utc": "2026-06-28 00:00:00", "to_utc": "2026-07-28 00:00:00", "timezone": "UTC", "all_dates": false, "date_field": "views" }, "filters": { "campaign_id": null }, "total": 12, "campaigns": [ { "campaign_id": 501, "name": "Spring Giveaway", "campaign_type": 9, "campaign_type_label": "Viral Sweepstakes", "created_at_utc": "2026-07-27 18:05:00", "promoted_link": null, "campaign_link": "https://\u2026/AbCdEf", "views": 128, "engagements": 34, "shares": 9, "referred_visits": 61, "leads": 4, "sales": 1, "revenue": 49, "currency": "USD", "referral_rewards": 2, "custom_conversions": [ { "event": "c1", "name": "", "count": 3 } ] } ], "meta": { "\u2026": "\u2026" } } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed \u2014 error.errors maps each field to its problem", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Workspace registration id", "schema": { "type": "integer" } }, { "name": "date_range", "in": "query", "required": false, "description": "The screen presets; ignored when from_utc/to_utc are sent", "schema": { "type": "string", "enum": [ "all", "last_30_days", "last_60_days", "last_90_days" ], "default": "last_30_days" } }, { "name": "from_utc", "in": "query", "required": false, "description": "ISO-8601 UTC start (custom range)", "schema": { "type": "string" } }, { "name": "to_utc", "in": "query", "required": false, "description": "ISO-8601 UTC end (custom range)", "schema": { "type": "string" } }, { "name": "date_field", "in": "query", "required": false, "description": "views = screen parity (a range returns only campaigns VIEWED in the window); created = filter on creation date", "schema": { "type": "string", "enum": [ "views", "created" ], "default": "views" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "restrict to one campaign", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "x-discovery": [ "workspaceId \u2190 GET /api/v1/workspaces", "campaign_id \u2190 POST /api/v1/sweepstakes, or the campaigns[] rows this endpoint returns" ], "operationId": "getCampaignsReport", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "attached_user_no_reports_permission", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "rate_limited", "validation_failed", "workspace_access_denied" ] } }, "/api/v1/posts/{id}/analytics": { "get": { "summary": "Post analytics", "description": "Delivery attempt log and per-network status for one post, with the full post view embedded. The attempt log (social_logs) is failure-biased on several platforms \u2014 an empty list does not mean no attempts; confirmed delivery is the per-network delivery_status on the post view. All timestamps UTC. ...", "tags": [ "Analytics" ], "x-permission": "analytics.read (plus posts.read for the embedded post view)", "responses": { "200": { "description": "Metrics", "content": { "application/json": { "example": { "post_id": 9001, "delivery_attempts": [ { "platform": "youtube", "response_code": 404, "attempted_at_utc": "2026-07-17 12:37:43" } ], "post": { "\u2026": "\u2026" }, "meta": { "\u2026": "\u2026" } } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "post_id", "schema": { "type": "integer" } } ], "x-discovery": [ "id \u2190 the post_id returned by POST /api/v1/posts" ], "operationId": "getPostAnalytics", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "attached_user_no_reports_permission", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited" ] } }, "/api/v1/sweepstakes": { "post": { "summary": "Create a Viral Sweepstakes", "description": "Creates a complete V2 Viral Sweepstakes from four fields; the builder automates the entry page, official rules, prizes and defaults exactly like the in-app wizard. Returns the shareable link and a ready-to-post social message.", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.create", "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "campaign_id": 501, "campaign_type": 9, "product": "Viral Sweepstakes", "title": "Spring Giveaway", "status": "draft", "theme": "0", "base_campaign": "0", "start_date": "2026-07-12 00:00:00", "end_date": "2026-08-11 00:00:00", "short_url": "AbCdEf", "sweepstakes_link": "https://\u2026/AbCdEf", "publish_to_social": "Enter our Spring Giveaway for a chance to win \u2026 https://\u2026/AbCdEf", "entry_form": { "name": null, "submission_form_id": 0, "opt_in": "single" }, "grand_prize": { "rank": 1, "name": "Grand Prize", "description": "\u2026", "image": null, "is_grand_prize": true }, "prizes": [ "\u2026" ], "official_rules_html": "

\u2026

", "settings": { "\u2026": "\u2026" } } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Campaign Title (shown on the entry page)." }, "description": { "type": "string", "description": "Campaign Description." }, "grand_prize_name": { "type": "string", "description": "Grand Prize Name." }, "grand_prize_description": { "type": "string", "description": "Grand Prize Description." }, "grand_prize_image_url": { "type": "string", "description": "Optional https image for the grand prize.", "x-omit-ok": true }, "background_image_url": { "type": "string", "description": "Optional https image used as the campaign page background. Applied with the editor defaults: image not repeated, black overlay at 0% opacity.", "x-omit-ok": true }, "additional_prizes": { "type": "array", "description": "Optional extra prizes.", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string", "x-omit-ok": true }, "image_url": { "type": "string", "description": "https only", "x-omit-ok": true } } }, "x-omit-ok": true }, "bonus_challenges": { "type": "array", "x-omit-ok": true, "description": "Optional Bonus Entry Challenges - extra actions an entrant can complete to earn more entries. Which fields are required depends on type. Display order follows the array order and is not settable; challenges are appended after the six built-in earn actions.", "items": { "type": "object", "required": [ "type", "label", "entries" ], "properties": { "type": { "type": "string", "description": "What the entrant does. button = click a button. button_question = click a button, then answer a validation question. question = answer a question. refer_friends = refer friends, tracked.", "enum": [ "button", "button_question", "question", "refer_friends" ] }, "label": { "type": "string", "description": "Challenge title shown on the entry page." }, "entries": { "type": "integer", "description": "Entries awarded on completion. 1 or more." }, "platform": { "type": "string", "description": "Groups the challenge and sets its default icon.", "enum": [ "facebook", "twitter", "instagram", "youtube", "tiktok", "linkedin", "pinterest", "twitch", "spotify", "review", "other" ], "default": "other" }, "description": { "type": "string", "description": "Longer copy shown under the label. HTML allowed.", "x-omit-ok": true }, "enabled": { "type": "boolean", "description": "false stores the challenge without showing it on the page.", "default": true }, "icon": { "type": "string", "description": "Font Awesome class, e.g. \"fab fa-facebook-f\".", "x-omit-ok": true }, "icon_color": { "type": "string", "description": "Hex colour for the icon, e.g. \"#1877F2\".", "x-omit-ok": true }, "repeat_every": { "type": "string", "description": "How often the entrant can earn this challenge again.", "enum": [ "campaign", "winner_selection_period", "second", "hour", "2hours", "6hours", "day", "2days", "3days", "week", "2weeks", "3weeks", "4weeks" ], "default": "campaign" }, "button_url": { "type": "string", "description": "Where the button sends the entrant. Required for button, button_question and refer_friends. http or https.", "x-omit-ok": true }, "button_text": { "type": "string", "description": "Button label. Required for button and button_question.", "x-omit-ok": true }, "question": { "type": "string", "description": "Required for button_question and question.", "x-omit-ok": true }, "question_type": { "type": "string", "description": "question type only.", "enum": [ "open-ended", "multiple-choice" ], "default": "open-ended" }, "choices": { "type": "array", "x-omit-ok": true, "items": { "type": "string" }, "description": "At least 2 choices. Required when question_type is multiple-choice." }, "accepted_answers": { "type": "array", "x-omit-ok": true, "items": { "type": "string" }, "description": "Answers that auto-approve the entry. Applies to button_question and question. Omit to accept any answer." }, "share_message": { "type": "string", "description": "Default share copy. Required for refer_friends.", "x-omit-ok": true }, "referral_tracks": { "type": "string", "description": "What counts as a successful referral. Required for refer_friends.", "x-omit-ok": true, "enum": [ "visits", "sales", "leads" ] } } } }, "theme": { "type": "string", "description": "Optional Campaign Theme - the name or id of a V2-enabled theme (GET /api/v1/sweepstakes/themes). Omit for the default look. Cannot be combined with base_campaign.", "x-omit-ok": true }, "base_campaign": { "type": "string", "description": "Optional template: the name or id of one of YOUR OWN campaigns to clone (GET /api/v1/sweepstakes/base-campaigns). Look AND behavior travel (design, bonus challenges, winner cadence, rules copy); prizes, dates, entry form and identity come from this request. Source: the agency primary workspace (agency credentials) or this workspace (workspace credentials); requires sweepstakes.read there. Cannot be combined with theme.", "x-omit-ok": true }, "start_date": { "type": "string", "description": "ISO-8601. Omit to start immediately.", "format": "date-time", "x-omit-ok": true }, "end_date": { "type": "string", "description": "ISO-8601. Omit for the default 30-day run.", "format": "date-time", "x-omit-ok": true }, "opt_in": { "type": "string", "description": "Entry-form email confirmation. Omitted = inherit the theme/base_campaign value when one is applied, otherwise single.", "enum": [ "single", "double" ], "x-omit-ok": true }, "entry_form": { "type": "string", "description": "Plain-English name of a saved entry form (GET /api/v1/sweepstakes/entry-forms). Omit for the default form.", "x-omit-ok": true }, "settings": { "type": "object", "description": "Optional Settings-tab overrides; every omitted control keeps its template default.", "x-omit-ok": true }, "publish": { "type": "boolean", "description": "false (default) saves a DRAFT; true creates the campaign live so its link works immediately.", "default": false }, "workspace_registration_id": { "type": "integer", "description": "Optional. Which workspace to create the campaign in. Workspace credentials always use their own workspace, so omit it. Agency credentials: omit to create in your agency's primary workspace, or pass an explicit workspace_registration_id (GET /api/v1/workspaces) to create in a different one of your workspaces.", "x-omit-ok": true } }, "required": [ "title", "description", "grand_prize_name", "grand_prize_description" ] }, "example": { "title": "Spring Giveaway", "description": "Win big this spring!", "grand_prize_name": "Grand Prize", "grand_prize_description": "A great prize." } } } }, "x-discovery": [ "entry_form names \u2190 GET /api/v1/sweepstakes/entry-forms", "theme name/id \u2190 GET /api/v1/sweepstakes/themes", "base_campaign name/id \u2190 GET /api/v1/sweepstakes/base-campaigns", "workspace_registration_id \u2190 GET /api/v1/workspaces (optional; omit to use the credential's own workspace)" ], "operationId": "createSweepstakes", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "creates a V2 Viral Sweepstakes (draft unless publish=true)", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "permission_denied", "rate_limited", "unsupported_campaign_type", "validation_failed", "workspace_required" ] } }, "/api/v1/sweepstakes/entry-forms": { "get": { "summary": "List saved entry forms", "description": "Plain-English names of the workspace's saved entry forms, usable as entry_form when creating a sweepstakes.", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.read", "responses": { "200": { "description": "Forms", "content": { "application/json": { "example": { "workspace_registration_id": 123456, "entry_forms": [ { "name": "Standard Entry", "submission_form_id": 12, "is_default": true } ] } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "workspace_registration_id", "in": "query", "required": false, "description": "Optional. Which workspace to act on. Workspace credentials always use their own workspace, so omit it. Agency credentials: omit to act on your agency's primary workspace, or pass an explicit workspace_registration_id (GET /api/v1/workspaces) to act on a different one of your workspaces.", "schema": { "type": "integer" } } ], "x-discovery": [ "entry_form values for POST /api/v1/sweepstakes come from here.", "workspace_registration_id \u2190 GET /api/v1/workspaces (optional override; omit to use the credential's own)" ], "operationId": "listSweepstakesEntryForms", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited", "validation_failed", "workspace_required" ] } }, "/api/v1/sweepstakes/themes": { "get": { "summary": "List Campaign Themes", "description": "V2-enabled Campaign Themes usable as the theme when creating a sweepstakes (by name or id).", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.read", "responses": { "200": { "description": "Themes", "content": { "application/json": { "example": { "themes": [ { "id": 36, "name": "Viral Sweepstakes", "premium": false } ] } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "workspace_registration_id", "in": "query", "required": false, "description": "Optional. Which workspace to act on. Workspace credentials always use their own workspace, so omit it. Agency credentials: omit to act on your agency's primary workspace, or pass an explicit workspace_registration_id (GET /api/v1/workspaces) to act on a different one of your workspaces.", "schema": { "type": "integer" } } ], "x-discovery": [ "theme values for POST /api/v1/sweepstakes come from here.", "workspace_registration_id \u2190 GET /api/v1/workspaces (optional override; omit to use the credential's own)" ], "operationId": "listSweepstakesThemes", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited", "validation_failed", "workspace_required" ] } }, "/api/v1/sweepstakes/base-campaigns": { "get": { "summary": "List base campaigns", "description": "Campaigns usable as base_campaign when creating a sweepstakes. The source workspace is fixed by credential type (agency primary workspace for agency credentials, own workspace for workspace credentials), so no workspace parameter is taken; requires sweepstakes.read on that source workspace. ...", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.read", "responses": { "200": { "description": "Base campaigns", "content": { "application/json": { "example": { "workspace_registration_id": 123456, "base_campaigns": [ { "campaign_id": 500, "name": "Real Estate Giveaway Template", "status": "draft", "status_label": "Draft" } ] } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "x-discovery": [ "base_campaign values for POST /api/v1/sweepstakes come from here. The source workspace is fixed by credential type, so this endpoint takes no workspace parameter." ], "operationId": "listSweepstakesBaseCampaigns", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited", "validation_failed", "workspace_required" ] } }, "/api/v1/sweepstakes/{id}": { "get": { "summary": "Get a sweepstakes", "description": "Full Sweepstakes-Console view of one campaign.", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "campaign_id": 501, "campaign_type": 9, "product": "Viral Sweepstakes", "title": "Spring Giveaway", "status": "draft", "theme": "0", "base_campaign": "0", "start_date": "2026-07-12 00:00:00", "end_date": "2026-08-11 00:00:00", "short_url": "AbCdEf", "sweepstakes_link": "https://\u2026/AbCdEf", "publish_to_social": "Enter our Spring Giveaway for a chance to win \u2026 https://\u2026/AbCdEf", "entry_form": { "name": null, "submission_form_id": 0, "opt_in": "single" }, "grand_prize": { "rank": 1, "name": "Grand Prize", "description": "\u2026", "image": null, "is_grand_prize": true }, "prizes": [ "\u2026" ], "official_rules_html": "

\u2026

", "settings": { "\u2026": "\u2026" } } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "campaign_id from POST /api/v1/sweepstakes", "schema": { "type": "integer" } }, { "name": "workspace_registration_id", "in": "query", "required": false, "description": "Optional. Which workspace to act on. Workspace credentials always use their own workspace, so omit it. Agency credentials: omit to act on your agency's primary workspace, or pass an explicit workspace_registration_id (GET /api/v1/workspaces) to act on a different one of your workspaces.", "schema": { "type": "integer" } } ], "x-discovery": [ "id \u2190 the campaign_id returned by POST /api/v1/sweepstakes, or the campaigns[] rows of GET /api/v1/workspaces/{workspaceId}/campaigns-report", "workspace_registration_id \u2190 GET /api/v1/workspaces (optional override; omit to use the credential's own)" ], "operationId": "getSweepstakes", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited", "validation_failed", "workspace_required" ] } }, "/api/v1/sweepstakes/{id}/entries": { "get": { "summary": "List entries", "description": "Paged entrant list (limit/offset query params, default 50).", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "entries": [ { "name": "Jane", "email": "jane@example.com" } ], "total": 1 } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "campaign_id from POST /api/v1/sweepstakes", "schema": { "type": "integer" } }, { "name": "workspace_registration_id", "in": "query", "required": false, "description": "Optional. Which workspace to act on. Workspace credentials always use their own workspace, so omit it. Agency credentials: omit to act on your agency's primary workspace, or pass an explicit workspace_registration_id (GET /api/v1/workspaces) to act on a different one of your workspaces.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Page offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "x-discovery": [ "id \u2190 the campaign_id returned by POST /api/v1/sweepstakes, or the campaigns[] rows of GET /api/v1/workspaces/{workspaceId}/campaigns-report", "workspace_registration_id \u2190 GET /api/v1/workspaces (optional override; omit to use the credential's own)" ], "operationId": "listSweepstakesEntries", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited", "validation_failed", "workspace_required" ] } }, "/api/v1/sweepstakes/{id}/referrals": { "get": { "summary": "List referrers", "description": "Per-entrant referral tallies.", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "referrers": [ { "crm_id": 5, "name": "Jane", "email": "jane@example.com" } ], "total_referrers": 1 } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "campaign_id from POST /api/v1/sweepstakes", "schema": { "type": "integer" } }, { "name": "workspace_registration_id", "in": "query", "required": false, "description": "Optional. Which workspace to act on. Workspace credentials always use their own workspace, so omit it. Agency credentials: omit to act on your agency's primary workspace, or pass an explicit workspace_registration_id (GET /api/v1/workspaces) to act on a different one of your workspaces.", "schema": { "type": "integer" } } ], "x-discovery": [ "id \u2190 the campaign_id returned by POST /api/v1/sweepstakes, or the campaigns[] rows of GET /api/v1/workspaces/{workspaceId}/campaigns-report", "workspace_registration_id \u2190 GET /api/v1/workspaces (optional override; omit to use the credential's own)" ], "operationId": "listSweepstakesReferrals", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited", "validation_failed", "workspace_required" ] } }, "/api/v1/sweepstakes/{id}/results": { "get": { "summary": "Results summary", "description": "Status, totals and winner state.", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.read", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "campaign_id": 501, "status": "publish", "total_entries": 42 } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "campaign_id from POST /api/v1/sweepstakes", "schema": { "type": "integer" } }, { "name": "workspace_registration_id", "in": "query", "required": false, "description": "Optional. Which workspace to act on. Workspace credentials always use their own workspace, so omit it. Agency credentials: omit to act on your agency's primary workspace, or pass an explicit workspace_registration_id (GET /api/v1/workspaces) to act on a different one of your workspaces.", "schema": { "type": "integer" } } ], "x-discovery": [ "id \u2190 the campaign_id returned by POST /api/v1/sweepstakes, or the campaigns[] rows of GET /api/v1/workspaces/{workspaceId}/campaigns-report", "workspace_registration_id \u2190 GET /api/v1/workspaces (optional override; omit to use the credential's own)" ], "operationId": "getSweepstakesResults", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited", "validation_failed", "workspace_required" ] } }, "/api/v1/sweepstakes/{id}/pause": { "post": { "summary": "Pause a sweepstakes", "description": "Pauses a live campaign.", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.create", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "campaign_id": 501, "status": "unpublish" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "campaign_id from POST /api/v1/sweepstakes", "schema": { "type": "integer" } }, { "name": "workspace_registration_id", "in": "query", "required": false, "description": "Optional. Which workspace to act on. Workspace credentials always use their own workspace, so omit it. Agency credentials: omit to act on your agency's primary workspace, or pass an explicit workspace_registration_id (GET /api/v1/workspaces) to act on a different one of your workspaces.", "schema": { "type": "integer" } } ], "x-discovery": [ "id \u2190 the campaign_id returned by POST /api/v1/sweepstakes, or the campaigns[] rows of GET /api/v1/workspaces/{workspaceId}/campaigns-report", "workspace_registration_id \u2190 GET /api/v1/workspaces (optional override; omit to use the credential's own)" ], "operationId": "pauseSweepstakes", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "pauses a running sweepstakes", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited", "validation_failed", "workspace_required" ] } }, "/api/v1/sweepstakes/{id}/duplicate": { "post": { "summary": "Duplicate a sweepstakes", "description": "Copies a campaign as a new draft.", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.create", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "campaign_id": 502, "status": "draft" } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "campaign_id from POST /api/v1/sweepstakes", "schema": { "type": "integer" } }, { "name": "workspace_registration_id", "in": "query", "required": false, "description": "Optional. Which workspace to act on. Workspace credentials always use their own workspace, so omit it. Agency credentials: omit to act on your agency's primary workspace, or pass an explicit workspace_registration_id (GET /api/v1/workspaces) to act on a different one of your workspaces.", "schema": { "type": "integer" } } ], "x-discovery": [ "id \u2190 the campaign_id returned by POST /api/v1/sweepstakes, or the campaigns[] rows of GET /api/v1/workspaces/{workspaceId}/campaigns-report", "workspace_registration_id \u2190 GET /api/v1/workspaces (optional override; omit to use the credential's own)" ], "operationId": "duplicateSweepstakes", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "creates a copy of the sweepstakes", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited", "validation_failed", "workspace_required" ] } }, "/api/v1/sweepstakes/{id}/promote": { "post": { "summary": "Promote assets", "description": "Opt-in promotion assets for a campaign: embed / button / sticky-tab / popup JS snippets (with slide-in options) and a QR code image URL. Nothing is returned unless requested.", "tags": [ "Viral Sweepstakes" ], "x-permission": "sweepstakes.read", "responses": { "200": { "description": "Assets", "content": { "application/json": { "example": { "sweepstakes_link": "https://\u2026/AbCdEf", "embeds": { "button": "" }, "qr": { "image_url": "https://\u2026/upload/qr_images/qr_501.png", "external_url": "https://api.qrserver.com/\u2026", "target": "https://\u2026/my-campaign/c501/", "stored": true } } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "402": { "description": "API access inactive (free-trial or suspended account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "403": { "description": "Permission denied for this API Agent in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "405": { "description": "That HTTP method is not supported on this endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "422": { "description": "Validation failed. error.code is validation_failed (error.errors maps each field to its problem), or workspace_required when the credential could not be matched to a workspace - pass workspace_registration_id to name the workspace this call should act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "429": { "description": "Rate limited \u2014 Retry-After tells you when to retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "500": { "description": "Unexpected server error \u2014 quote error.request_id to support", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "503": { "description": "api_access_disabled \u2014 API access is temporarily disabled platform-wide (global kill switch); retry later", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "campaign_id", "schema": { "type": "integer" } }, { "name": "workspace_registration_id", "in": "query", "required": false, "description": "Optional. Which workspace to act on. Workspace credentials always use their own workspace, so omit it. Agency credentials: omit to act on your agency's primary workspace, or pass an explicit workspace_registration_id (GET /api/v1/workspaces) to act on a different one of your workspaces.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "embeds": { "type": "array", "items": { "type": "string", "enum": [ "iframe", "button", "stickytab", "popup" ] }, "description": "Which snippets to return. Omit for none.", "x-omit-ok": true }, "qr": { "type": "boolean", "description": "Include a QR code image URL.", "default": false }, "qr_size": { "type": "integer", "description": "QR pixel size. Sizes outside the supported range are clamped into it.", "default": 500, "minimum": 150, "maximum": 2000 }, "options": { "type": "object", "x-omit-ok": true, "description": "Snippet options; omitted options keep the campaign's stored values. fly_in_effect, delay_seconds, position, title and only_on_first_visit are the slide-in settings for the popup and stickytab snippets and are PERSISTED to the campaign. button_image_name and button_image_height style the button snippet. A value that is not a valid UI value is reported in warnings and not persisted.", "properties": { "fly_in_effect": { "type": "string", "description": "Slide-in direction for the popup / stickytab snippet. The stored forms no_fly, fly_right and fly_left are accepted too.", "x-omit-ok": true, "enum": [ "none", "right", "left" ] }, "delay_seconds": { "type": "integer", "description": "Open the popup this many seconds after the page loads. 0 opens it immediately.", "default": 0 }, "position": { "type": "string", "description": "Sticky-tab orientation.", "x-omit-ok": true, "enum": [ "vertical", "horizontal" ] }, "title": { "type": "string", "description": "Sticky-tab title text.", "x-omit-ok": true }, "only_on_first_visit": { "type": "boolean", "description": "Show the popup / sticky tab only on a visitor's first visit.", "default": false }, "button_image_name": { "type": "string", "description": "Needed by the button snippet: the Asset Library image filename, exactly as shown in the Design step. If you omit it the button snippet is still returned but renders EMPTY, and the omission is reported in warnings only - never as an error. Pass it whenever you request the button embed.", "x-omit-ok": true }, "button_image_height": { "type": "integer", "description": "Height in pixels of the button image.", "default": 60 } } } }, "required": [] }, "example": { "embeds": [ "button" ], "qr": true } } } }, "x-discovery": [ "id \u2190 the campaign_id returned by POST /api/v1/sweepstakes, or the campaigns[] rows of GET /api/v1/workspaces/{workspaceId}/campaigns-report", "workspace_registration_id \u2190 GET /api/v1/workspaces (optional override; omit to use the credential's own)", "options.button_image_name \u2190 an Asset Library image filename, as listed in the campaign Design step" ], "operationId": "promoteSweepstakes", "x-product": "both", "x-plan-requirement": "Included with every paid plan", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "persists slide-in settings when promote options are given", "x-error-codes": [ "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "not_found", "permission_denied", "rate_limited", "validation_failed", "workspace_required" ] } } } }