{ "openapi": "3.1.0", "info": { "title": "Sociamonials API", "version": "1.2.0", "description": "Authenticate every request with the header \"Authorization: Bearer \". Create a key at https://www.sociamonials.com/login.php?redirect=accounts%2Fapi_keys.php (sign in first, then Create API Key). Call GET /api/v1/me first: it reports exactly what your key may do. Browsable docs: https://www.sociamonials.com/developers.php\n\nREST API for social publishing, viral sweepstakes and analytics. Authenticate every request with an API Agent credential in the Authorization header. The same permissions, approval routing, entitlements and rate limits apply to the MCP server. Rate limits per credential: 120 reads/min and 30 writes/min (agency agents get double); identity and discovery endpoints are exempt. Your live limit is in the X-RateLimit-Limit header and a 429 includes Retry-After. Daily sending limits per workspace: 1,000 posts, 100 tweets (tweets cannot contain links; Enterprise workspaces may post up to 50 tweets with links per month), 100 Pinterest pins, and 10 YouTube uploads per channel per 24 hours. Null policy: for any optional field, sending null (or the literal string \"null\") is identical to omitting it \u2014 the documented default applies silently. Required fields that are missing, null, or empty return a 422 naming the field. Unknown field names are ignored and reported in the warnings array of the response (with strict:true they return a 422 instead, where supported). image_url (singular) is accepted as an alias of image_urls. Errors are JSON: {\"error\": {\"code\", \"message\", \"request_id\"}}. 401 invalid_credentials (missing or invalid credential); 402 api_subscription_inactive (API access is not active for this account: free trial, or account suspended - the code name is retained for contract compatibility); 403 permission or profile not granted; 404 not found; 409 conflict; 422 validation_failed (error.errors maps each field to its problem), or workspace_required on the sweepstakes operations when the credential could not be matched to a workspace; 429 rate limited (Retry-After tells you when to retry); 503 api_access_disabled (API access is temporarily disabled platform-wide; retry later). 402 and 503 are returned before routing, so every operation can return them; 429 applies to every operation except the rate-exempt identity and discovery endpoints. Every error carries request_id once the request reaches the API logging middleware - quote it to support. Error responses never contain an exception message or stack trace." }, "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)", "agency_agent_required": "The operation needs an AGENCY API Agent; this is a workspace credential. (403)", "agencypro_required": "The agency does not have an active AgencyPro subscription. (403)", "client_not_owned": "That client workspace is not linked to your agency. (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)", "cannot_reissue": "The onboarding link cannot be re-issued - the provision is unknown, or the client already finished onboarding (use a login link instead). (409)", "existing_account": "That email already has an account on the platform. (409)", "idempotency_in_flight": "An earlier request with the same Idempotency-Key is still running. Retry shortly. (409)", "provision_limit_reached": "The agency's daily client-provisioning cap has been reached. Retry tomorrow. (403)", "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, "agency_agent_required": 403, "agencypro_required": 403, "client_not_owned": 403, "provision_limit_reached": 403, "not_found": 404, "method_not_allowed": 405, "cannot_cancel": 409, "cannot_reissue": 409, "existing_account": 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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/me' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/me', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/me',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/workspaces' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/workspaces',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/workspaces/123456/social-profiles' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/123456/social-profiles', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/workspaces/123456/social-profiles',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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, pinterest.board_name) resolve against your saved items \u2014 unknown names are reported in the warnings array of the response, never as hard failures. If the agent lacks posts.publish_direct, non-draft posts route through the workspace approval flow (status pending_approval). Null policy: for any optional field, sending null (or the literal string \"null\") is identical to omitting it \u2014 the documented default applies silently. Required fields that are missing, null, or empty return a 422 naming the field. Unknown field names are ignored and reported in the warnings array of the response (with strict:true they return a 422 instead, where supported). image_url (singular) is accepted as an alias of image_urls. 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). NOTE the two different structures: profile_selection.networks (an ARRAY of codes) chooses DESTINATION networks and resolves each workspace's default-on profiles; the networks OBJECT here carries network-specific CONTENT (message overrides and per-network options) plus profile_refs when you select profiles explicitly. Do not confuse the two.", "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). NOTE the two different structures: profile_selection.networks (an ARRAY of codes) chooses DESTINATION networks and resolves each workspace's default-on profiles; the networks OBJECT here carries network-specific CONTENT (message overrides and per-network options) plus profile_refs when you select profiles explicitly. 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 }, "profile_selection": { "type": "object", "description": "AGENCY API Agents only: select profiles BY NETWORK instead of listing profile ids. Each target workspace resolves its own default-on profiles \u2014 the same workspace defaults the AgencyPro automated posting assistant uses \u2014 excluding disconnected profiles and profiles not assigned to your agent (default-on is not permission). Selection precedence: post_preset, then explicit networks..profile_refs, then profile_selection; anything overridden is reported in warnings. The response reports the resolved profiles per workspace in profile_resolution.", "properties": { "mode": { "type": "string", "description": "V1 supports 'default_on_by_network' only.", "enum": [ "default_on_by_network" ], "x-omit-ok": true }, "networks": { "type": "array", "items": { "type": "string" }, "description": "Network codes (fb, tw, ln, in, pi, gmb, thrd, tiktok, yt, blsk). Unknown codes are rejected.", "x-omit-ok": true } }, "x-omit-ok": true, "x-product": "agency" }, "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-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/posts' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE' \\\n -H 'Idempotency-Key: my-safe-retry-key-1' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"mode\": \"draft\",\n \"message\": \"Hello from the API!\",\n \"networks\": {\n \"fb\": {\n \"profile_refs\": [\n \"YOUR_PROFILE_ID\"\n ]\n }\n }\n}'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/posts', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"mode\": \"draft\",\n \"message\": \"Hello from the API!\",\n \"networks\": {\n \"fb\": {\n \"profile_refs\": [\n \"YOUR_PROFILE_ID\"\n ]\n }\n }\n}),\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/posts',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n 'Idempotency-Key': 'my-safe-retry-key-1',\n },\n json={ 'mode': 'draft',\n 'message': 'Hello from the API!',\n 'networks': {'fb': {'profile_refs': ['YOUR_PROFILE_ID']}}},\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type: application/json',\n 'Idempotency-Key: my-safe-retry-key-1',\n ],\n CURLOPT_POSTFIELDS => $body,\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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. Facebook video uploads), delivered (the network returned a post id), or failed (with the error message) \u2014 so workflows can poll until a final state. The per-network delivered boolean is true only once the platform confirmed the post.", "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/posts/9001' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/posts/9001', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/posts/9001',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X DELETE 'https://www.sociamonials.com/api/v1/posts/9001' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/posts/9001', {\n method: 'DELETE',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.delete(\n 'https://www.sociamonials.com/api/v1/posts/9001',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'DELETE',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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/publish": { "post": { "summary": "Publish to many workspaces (agency)", "description": "Agency bulk operation: the same post content fanned out to multiple workspaces in one call. Per-workspace permission checks apply independently; the response reports each workspace separately. Every post field documented on POST /api/v1/posts applies here: a top-level value is shared across all targets, and the same key inside a workspaces[] entry overrides it for that workspace. Null policy: for any optional field, sending null (or the literal string \"null\") is identical to omitting it \u2014 the documented default applies silently. Required fields that are missing, null, or empty return a 422 naming the field. Unknown field names are ignored and reported in the warnings array of the response (with strict:true they return a 422 instead, where supported). image_url (singular) is accepted as an alias of image_urls.", "tags": [ "Publishing" ], "x-permission": "posts.create + posts.schedule in every target workspace", "responses": { "200": { "description": "Accepted", "content": { "application/json": { "example": { "job_id": 77, "status": "completed", "results": [ { "workspace_registration_id": 123456, "status": "created", "post_id": 9002 } ] } } } }, "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": { "workspaces": { "type": "array", "description": "The target workspaces. Each entry is an object with workspace_registration_id plus any per-workspace overrides of the post fields (message, networks, post_preset, publish_at, \u2026). A bare workspace id number is also accepted where no overrides are needed.", "items": { "type": "object", "required": [ "workspace_registration_id" ], "properties": { "workspace_registration_id": { "type": "integer", "description": "Target workspace id (GET /api/v1/workspaces)." } }, "additionalProperties": true } }, "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). NOTE the two different structures: profile_selection.networks (an ARRAY of codes) chooses DESTINATION networks and resolves each workspace's default-on profiles; the networks OBJECT here carries network-specific CONTENT (message overrides and per-network options) plus profile_refs when you select profiles explicitly. 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 }, "profile_selection": { "type": "object", "description": "AGENCY API Agents only: select profiles BY NETWORK instead of listing profile ids. Each target workspace resolves its own default-on profiles \u2014 the same workspace defaults the AgencyPro automated posting assistant uses \u2014 excluding disconnected profiles and profiles not assigned to your agent (default-on is not permission). Selection precedence: post_preset, then explicit networks..profile_refs, then profile_selection; anything overridden is reported in warnings. The response reports the resolved profiles per workspace in profile_resolution.", "properties": { "mode": { "type": "string", "description": "V1 supports 'default_on_by_network' only.", "enum": [ "default_on_by_network" ], "x-omit-ok": true }, "networks": { "type": "array", "items": { "type": "string" }, "description": "Network codes (fb, tw, ln, in, pi, gmb, thrd, tiktok, yt, blsk). Unknown codes are rejected.", "x-omit-ok": true } }, "x-omit-ok": true, "x-product": "agency" }, "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": [ "workspaces", "mode" ] }, "example": { "workspaces": [ { "workspace_registration_id": 123456 } ], "mode": "draft", "message": "Network-wide update", "networks": { "fb": { "profile_refs": [ "YOUR_PROFILE_ID" ] } } } } } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/workspaces/publish' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"workspaces\": [\n {\n \"workspace_registration_id\": 123456\n }\n ],\n \"mode\": \"draft\",\n \"message\": \"Network-wide update\",\n \"networks\": {\n \"fb\": {\n \"profile_refs\": [\n \"YOUR_PROFILE_ID\"\n ]\n }\n }\n}'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/publish', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"workspaces\": [\n {\n \"workspace_registration_id\": 123456\n }\n ],\n \"mode\": \"draft\",\n \"message\": \"Network-wide update\",\n \"networks\": {\n \"fb\": {\n \"profile_refs\": [\n \"YOUR_PROFILE_ID\"\n ]\n }\n }\n}),\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/workspaces/publish',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n },\n json={ 'workspaces': [{'workspace_registration_id': 123456}],\n 'mode': 'draft',\n 'message': 'Network-wide update',\n 'networks': {'fb': {'profile_refs': ['YOUR_PROFILE_ID']}}},\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => $body,\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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": [ "workspaces[].workspace_registration_id \u2190 GET /api/v1/workspaces", "profile_refs \u2190 GET /api/v1/workspaces/{workspaceId}/social-profiles, per target workspace" ], "operationId": "publishToWorkspaces", "x-product": "agency", "x-plan-requirement": "Included with every paid plan; the Agency API also requires an active AgencyPro subscription", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "creates posts in MULTIPLE client workspaces", "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", "rate_limited", "validation_failed" ], "x-partial-failure-codes": [ "permission_denied", "profile_not_assigned", "validation_failed" ] } }, "/api/v1/jobs/{id}": { "get": { "summary": "Bulk job status", "description": "Progress and per-workspace results of a bulk publish job.", "tags": [ "Publishing" ], "x-permission": "none \u2014 any active credential", "responses": { "200": { "description": "Job", "content": { "application/json": { "example": { "job_id": 77, "status": "completed", "results": [ { "workspace_registration_id": 123456, "post_id": 9002 } ] } } } }, "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": "job_id from POST /api/v1/workspaces/publish", "schema": { "type": "integer" } } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/jobs/77' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/jobs/77', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/jobs/77',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "x-discovery": [ "id \u2190 the job_id returned by POST /api/v1/workspaces/publish" ], "operationId": "getJob", "x-product": "agency", "x-plan-requirement": "Included with every paid plan; the Agency API also requires an active AgencyPro subscription", "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" ] } }, "/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. V1 is delivery-focused \u2014 engagement metrics are not included yet and every response discloses this in meta.partial_data.", "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/workspaces/123456/analytics?from_utc=2026-06-12T00:00:00Z' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/123456/analytics?from_utc=2026-06-12T00:00:00Z', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/workspaces/123456/analytics?from_utc=2026-06-12T00:00:00Z',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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, and the account-defined custom_conversions - the conversion-tracking events this WORKSPACE defined in its own preferences, returned by their own names (there are no fixed custom-conversion fields; a workspace with none configured returns an empty array). Screen-parity semantics, stated in meta: click/conversion counts are LIFETIME totals per message - the date range selects which messages appear, not which clicks count; a networks filter also restricts which networks' clicks/conversions count; likes/comments are cached network counters with no Twitter/X engagement.", "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/workspaces/123456/published-messages?date_range=last_30_days' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/123456/published-messages?date_range=last_30_days', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/workspaces/123456/published-messages?date_range=last_30_days',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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. Reporting is type-agnostic; CREATING and managing campaigns through this API remains V2 Viral Sweepstakes only. Each row carries campaign_type (the numeric product type, always present) and campaign_type_label (the template name the screen prints, null when that template row no longer exists), promoted_link (the screen column reproduced exactly - null for several products, including every viral sweepstakes, whose link configuration that column does not handle) and campaign_link (the campaign public link that actually works), plus views, engagements, shares, referred_visits, leads, sales, revenue (numeric USD), referral_rewards and the workspace-defined custom_conversions. Metric semantics are stated in meta.", "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/workspaces/123456/campaigns-report?date_range=last_30_days' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/123456/campaigns-report?date_range=last_30_days', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/workspaces/123456/campaigns-report?date_range=last_30_days',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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/analytics/agency": { "get": { "summary": "Agency roll-up analytics", "description": "Per-workspace delivery summaries for every workspace where this agent holds analytics.read, ranked by dispatched posts. Same window rules and metric definitions as workspace analytics.", "tags": [ "Analytics" ], "x-permission": "analytics.read (evaluated per workspace)", "responses": { "200": { "description": "Metrics", "content": { "application/json": { "example": { "window": { "from_utc": "2026-06-12 00:00:00", "to_utc": "2026-07-12 00:00:00", "timezone": "UTC" }, "workspaces_ranked_by_delivered": [ { "workspace_registration_id": 123456, "totals": { "\u2026": "\u2026" }, "by_network": { "\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." } } } } } } } }, "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": "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/analytics/agency' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/analytics/agency', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/analytics/agency',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "operationId": "getAgencyAnalytics", "x-product": "agency", "x-plan-requirement": "Included with every paid plan; the Agency API also requires an active AgencyPro subscription", "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", "rate_limited", "validation_failed" ] } }, "/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. V1 is delivery-focused; engagement metrics are not included yet.", "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/posts/9001/analytics' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/posts/9001/analytics', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/posts/9001/analytics',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/sweepstakes' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"title\": \"Spring Giveaway\",\n \"description\": \"Win big this spring!\",\n \"grand_prize_name\": \"Grand Prize\",\n \"grand_prize_description\": \"A great prize.\"\n}'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"title\": \"Spring Giveaway\",\n \"description\": \"Win big this spring!\",\n \"grand_prize_name\": \"Grand Prize\",\n \"grand_prize_description\": \"A great prize.\"\n}),\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/sweepstakes',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n },\n json={ 'title': 'Spring Giveaway',\n 'description': 'Win big this spring!',\n 'grand_prize_name': 'Grand Prize',\n 'grand_prize_description': 'A great prize.'},\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => $body,\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/sweepstakes/entry-forms' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes/entry-forms', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/sweepstakes/entry-forms',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/sweepstakes/themes' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes/themes', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/sweepstakes/themes',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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. Draft and paused campaigns are valid bases.", "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/sweepstakes/base-campaigns' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes/base-campaigns', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/sweepstakes/base-campaigns',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/sweepstakes/501' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes/501', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/sweepstakes/501',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/sweepstakes/501/entries' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes/501/entries', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/sweepstakes/501/entries',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/sweepstakes/501/referrals' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes/501/referrals', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/sweepstakes/501/referrals',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/sweepstakes/501/results' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes/501/results', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/sweepstakes/501/results',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/sweepstakes/501/pause' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes/501/pause', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/sweepstakes/501/pause',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/sweepstakes/501/duplicate' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes/501/duplicate', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/sweepstakes/501/duplicate',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/sweepstakes/501/promote' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"embeds\": [\n \"button\"\n ],\n \"qr\": true\n}'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/sweepstakes/501/promote', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"embeds\": [\n \"button\"\n ],\n \"qr\": true\n}),\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/sweepstakes/501/promote',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n },\n json={'embeds': ['button'], 'qr': True},\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => $body,\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "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" ] } }, "/api/v1/workspaces/provision": { "post": { "summary": "Provision a client workspace", "description": "AGENCY + AgencyPro only. Create a NEW client workspace under one of your Pricing Plans WITHOUT charging \u2014 the plan's price is ignored, only its provisioning settings (limits, screens, required fields) are used. You get back an onboarding_url (valid 7 days, single-use) that hands the customer straight into set-password and the plan's onboarding screens, skipping the payment and signup-form steps. The account itself is created when the customer opens the link, through the normal signup flow \u2014 so API-provisioned clients are identical to UI-provisioned ones. No password is accepted here (the customer sets it at handoff). If the email already has an account, you get existing_account (409). A per-agency daily cap applies (admin-configurable).", "tags": [ "Provisioning" ], "x-permission": "clients.provision (Agency API Agent, AgencyPro)", "responses": { "201": { "description": "Provisioned", "content": { "application/json": { "example": { "provision_id": 4021, "onboarding_url": "https://social.partnerco.com/sm_workspace_onboard.php?hp=sm_onb_...", "expires_at": "2026-07-22T00:00:00+00:00", "missing_required_fields": [ "phone" ], "status": "pending" } } } }, "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": { "pricing_plan": { "type": "string", "description": "Your Pricing Plan name (exact) or numeric id. Must belong to your agency and be active." }, "customer": { "type": "object", "description": "The new client's contact info. email is required; the rest are optional and can also be collected on the onboarding screen.", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Required. The client's email; must not already have an account on the platform." }, "first_name": { "type": "string", "description": "Optional.", "x-omit-ok": true }, "last_name": { "type": "string", "description": "Optional.", "x-omit-ok": true }, "company": { "type": "string", "description": "Optional.", "x-omit-ok": true }, "phone": { "type": "string", "description": "Optional.", "x-omit-ok": true }, "website": { "type": "string", "description": "Optional.", "x-omit-ok": true }, "username": { "type": "string", "description": "Optional; auto-generated if omitted.", "x-omit-ok": true }, "timezone": { "type": "string", "description": "Optional IANA timezone, e.g. America/Chicago.", "x-omit-ok": true }, "industry": { "type": "string", "description": "Industry id. Required for new accounts unless the plan forces one; if omitted it is collected on the client's onboarding screen (appears in missing_required_fields).", "x-omit-ok": true } } }, "suppress_emails": { "type": "boolean", "description": "Default true \u2014 your app owns comms. Set false to send the agency's normal client welcome/notify emails.", "default": true } }, "required": [ "pricing_plan", "customer" ] }, "example": { "pricing_plan": "Contractor Social Basic", "customer": { "email": "jane@acme.com", "first_name": "Jane", "company": "Acme Roofing" }, "suppress_emails": true } } } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/workspaces/provision' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"pricing_plan\": \"Contractor Social Basic\",\n \"customer\": {\n \"email\": \"jane@acme.com\",\n \"first_name\": \"Jane\",\n \"company\": \"Acme Roofing\"\n },\n \"suppress_emails\": true\n}'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/provision', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"pricing_plan\": \"Contractor Social Basic\",\n \"customer\": {\n \"email\": \"jane@acme.com\",\n \"first_name\": \"Jane\",\n \"company\": \"Acme Roofing\"\n },\n \"suppress_emails\": true\n}),\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/workspaces/provision',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n },\n json={ 'pricing_plan': 'Contractor Social Basic',\n 'customer': { 'email': 'jane@acme.com',\n 'first_name': 'Jane',\n 'company': 'Acme Roofing'},\n 'suppress_emails': True},\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => $body,\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "x-discovery": [ "pricing_plan \u2190 one of your own agency Pricing Plans, by exact name or numeric id. There is no API endpoint that lists them; they come from your agency settings." ], "operationId": "provisionClientWorkspace", "x-product": "agency", "x-plan-requirement": "Included with every paid plan; the Agency API also requires an active AgencyPro subscription", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "creates a PENDING client provision and onboarding link", "x-error-codes": [ "agency_agent_required", "agencypro_required", "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "credentials_in_query_string", "existing_account", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "permission_denied", "provision_limit_reached", "rate_limited", "validation_failed" ] } }, "/api/v1/workspaces/provision/{id}": { "get": { "summary": "Provision status", "description": "Poll a provision request. Returns status (pending until the customer completes onboarding, then redeemed) and, once created, the workspace_registration_id of the new client.", "tags": [ "Provisioning" ], "x-permission": "clients.provision", "responses": { "200": { "description": "Status", "content": { "application/json": { "example": { "provision_id": 4021, "status": "redeemed", "workspace_registration_id": 40233, "pricing_plan": "Contractor Social Basic", "email": "jane@acme.com", "missing_required_fields": [], "expires_at": "2026-07-22T00:00:00+00:00", "redeemed_at": "2026-07-15T18:10:00+00:00" } } } }, "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": "provision_id from POST /workspaces/provision", "schema": { "type": "integer" } } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.sociamonials.com/api/v1/workspaces/provision/4021' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/provision/4021', {\n method: 'GET',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.get(\n 'https://www.sociamonials.com/api/v1/workspaces/provision/4021',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'GET',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "x-discovery": [ "id \u2190 the provision_id returned by POST /api/v1/workspaces/provision" ], "operationId": "getClientProvisionStatus", "x-product": "agency", "x-plan-requirement": "Included with every paid plan; the Agency API also requires an active AgencyPro subscription", "x-rate-class": "read", "x-rate-cost": "1 request from the read bucket", "x-side-effects": "none", "x-error-codes": [ "agency_agent_required", "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" ] } }, "/api/v1/workspaces/provision/{id}/handoff": { "post": { "summary": "Re-issue an onboarding link", "description": "Mint a fresh 7-day onboarding link for a provision that has not been completed yet (e.g. the first link expired). Fails if the client already finished onboarding \u2014 use a login link instead.", "tags": [ "Provisioning" ], "x-permission": "clients.provision", "responses": { "200": { "description": "Reissued", "content": { "application/json": { "example": { "provision_id": 4021, "onboarding_url": "https://social.partnerco.com/sm_workspace_onboard.php?hp=sm_onb_...", "expires_at": "2026-07-29T00:00:00+00:00", "status": "pending" } } } }, "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." } } } } } } } }, "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": "provision_id", "schema": { "type": "integer" } } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/workspaces/provision/4021/handoff' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/provision/4021/handoff', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/workspaces/provision/4021/handoff',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "x-discovery": [ "id \u2190 the provision_id returned by POST /api/v1/workspaces/provision" ], "operationId": "reissueClientOnboardingLink", "x-product": "agency", "x-plan-requirement": "Included with every paid plan; the Agency API also requires an active AgencyPro subscription", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "re-issues the onboarding link", "x-error-codes": [ "agency_agent_required", "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "cannot_reissue", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "rate_limited" ] } }, "/api/v1/workspaces/{id}/login-link": { "post": { "summary": "Client login link", "description": "AGENCY + AgencyPro only. Mint a short-lived (~10 minute), single-use sign-in link for an EXISTING client workspace you provisioned, so a user working inside your app can jump straight into their social workspace without a password. Scoped: only works for workspaces linked to your agency. Request a fresh link at the moment the user clicks through \u2014 the short lifetime means a leaked link is almost always already dead.", "tags": [ "Provisioning" ], "x-permission": "clients.provision (Agency API Agent, AgencyPro)", "responses": { "201": { "description": "Login link", "content": { "application/json": { "example": { "workspace_registration_id": 40233, "login_url": "https://social.partnerco.com/sm_workspace_onboard.php?lp=sm_lgn_...", "expires_at": "2026-07-15T18:20:00+00:00" } } } }, "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." } } } } } } } }, "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": "the client workspace_registration_id", "schema": { "type": "integer" } } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/workspaces/40233/login-link' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/40233/login-link', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/workspaces/40233/login-link',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "x-discovery": [ "id \u2190 the workspace_registration_id of a client linked to your agency (GET /api/v1/workspaces, or GET /api/v1/workspaces/provision/{id} once it is redeemed)" ], "operationId": "createClientLoginLink", "x-product": "agency", "x-plan-requirement": "Included with every paid plan; the Agency API also requires an active AgencyPro subscription", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "mints a 10-minute single-use client sign-in link", "x-error-codes": [ "agency_agent_required", "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "client_not_owned", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "permission_denied", "rate_limited" ] } }, "/api/v1/workspaces/{id}/pause": { "post": { "summary": "Pause a client workspace", "description": "AGENCY + AgencyPro only. Pause is THE way to make a client workspace inaccessible: the client can no longer sign in and the workspace is hidden in the agency dashboard, while scheduled content and data stay untouched. Fully reversible with /resume. (Deleting is separate, permanent, and irreversible.) Scoped: only clients linked to your agency.", "tags": [ "Provisioning" ], "x-permission": "clients.provision (Agency API Agent, AgencyPro)", "responses": { "200": { "description": "Paused", "content": { "application/json": { "example": { "workspace_registration_id": 40233, "status": "paused" } } } }, "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 \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": "id", "in": "path", "required": true, "description": "the client workspace_registration_id", "schema": { "type": "integer" } } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/workspaces/40233/pause' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/40233/pause', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/workspaces/40233/pause',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "x-discovery": [ "id \u2190 the workspace_registration_id of a client linked to your agency (GET /api/v1/workspaces, or GET /api/v1/workspaces/provision/{id} once it is redeemed)" ], "operationId": "pauseClientWorkspace", "x-product": "agency", "x-plan-requirement": "Included with every paid plan; the Agency API also requires an active AgencyPro subscription", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "blocks client sign-in and hides the workspace (reversible)", "x-error-codes": [ "agency_agent_required", "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "client_not_owned", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "permission_denied", "rate_limited", "validation_failed" ] } }, "/api/v1/workspaces/{id}/resume": { "post": { "summary": "Resume a paused client workspace", "description": "Reverse of /pause: re-enables sign-in and dashboard visibility for the client workspace.", "tags": [ "Provisioning" ], "x-permission": "clients.provision (Agency API Agent, AgencyPro)", "responses": { "200": { "description": "Resumed", "content": { "application/json": { "example": { "workspace_registration_id": 40233, "status": "active" } } } }, "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 \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": "id", "in": "path", "required": true, "description": "the client workspace_registration_id", "schema": { "type": "integer" } } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/v1/workspaces/40233/resume' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/40233/resume', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/v1/workspaces/40233/resume',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "x-discovery": [ "id \u2190 the workspace_registration_id of a client linked to your agency (GET /api/v1/workspaces, or GET /api/v1/workspaces/provision/{id} once it is redeemed)" ], "operationId": "resumeClientWorkspace", "x-product": "agency", "x-plan-requirement": "Included with every paid plan; the Agency API also requires an active AgencyPro subscription", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "restores client sign-in and visibility", "x-error-codes": [ "agency_agent_required", "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "client_not_owned", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "permission_denied", "rate_limited", "validation_failed" ] } }, "/api/v1/workspaces/{id}": { "delete": { "summary": "Delete a client workspace (PERMANENT)", "description": "AGENCY + AgencyPro only. Deletes a client workspace: PERMANENT and IRREVERSIBLE \u2014 the same as Delete in the agency dashboard. The account is flagged deleted platform-wide, unlinked from your agency, and sign-in is disabled forever. There is no undelete and no reactivation; provisioning again creates a brand-new workspace. If you only want to make the workspace inaccessible for a while, use /pause instead \u2014 that is the reversible operation. No money is involved (API-provisioned workspaces are never charged).", "tags": [ "Provisioning" ], "x-permission": "clients.provision (Agency API Agent, AgencyPro)", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "example": { "workspace_registration_id": 40233, "status": "deleted" } } } }, "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 \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": "id", "in": "path", "required": true, "description": "the client workspace_registration_id", "schema": { "type": "integer" } } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl -X DELETE 'https://www.sociamonials.com/api/v1/workspaces/40233' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/v1/workspaces/40233', {\n method: 'DELETE',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.delete(\n 'https://www.sociamonials.com/api/v1/workspaces/40233',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n },\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'DELETE',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n ],\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "x-discovery": [ "id \u2190 the workspace_registration_id of a client linked to your agency (GET /api/v1/workspaces, or GET /api/v1/workspaces/provision/{id} once it is redeemed)" ], "operationId": "deleteClientWorkspace", "x-product": "agency", "x-plan-requirement": "Included with every paid plan; the Agency API also requires an active AgencyPro subscription", "x-rate-class": "write", "x-rate-cost": "1 request from the write bucket", "x-side-effects": "PERMANENT, irreversible delete of the client workspace", "x-error-codes": [ "agency_agent_required", "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "client_not_owned", "credentials_in_query_string", "http_error", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "permission_denied", "rate_limited", "validation_failed" ] } }, "/api/mcp": { "post": { "summary": "MCP server (Streamable HTTP)", "description": "The Model Context Protocol endpoint for AI assistants (Claude, ChatGPT connectors, n8n MCP client, \u2026). Same credential, permissions and rate limits as REST. Send MCP JSON-RPC (initialize, tools/list, tools/call) with Accept: application/json, text/event-stream. Authentication is a bearer credential \u2014 not OAuth.", "tags": [ "MCP" ], "x-permission": "per tool \u2014 mirrors the REST permission of the equivalent operation", "responses": { "200": { "description": "JSON-RPC result", "content": { "application/json": { "example": { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-06-18", "serverInfo": { "name": "social-publishing-mcp", "version": "1.0.0" } } } } } }, "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": { "jsonrpc": { "type": "string", "description": "Always '2.0'." }, "id": { "type": "integer" }, "method": { "type": "string", "description": "initialize | tools/list | tools/call" }, "params": { "type": "object", "description": "Method parameters. Omit for methods that take none.", "x-omit-ok": true } }, "required": [ "jsonrpc", "id", "method" ] }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": [] } } } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.sociamonials.com/api/mcp' \\\n -H 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE' \\\n -H 'Accept: application/json, text/event-stream' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/list\",\n \"params\": {}\n}'" }, { "lang": "JavaScript", "source": "const res = await fetch('https://www.sociamonials.com/api/mcp', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/list\",\n \"params\": {}\n}),\n});\nconst data = await res.json();" }, { "lang": "Python", "source": "import requests\n\nres = requests.post(\n 'https://www.sociamonials.com/api/mcp',\n headers={\n 'Authorization': 'Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type': 'application/json',\n 'Accept': 'application/json, text/event-stream',\n },\n json={'jsonrpc': '2.0', 'id': 1, 'method': 'tools/list', 'params': {}},\n)\ndata = res.json()" }, { "lang": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer PASTE_YOUR_API_KEY_HERE',\n 'Content-Type: application/json',\n 'Accept: application/json, text/event-stream',\n ],\n CURLOPT_POSTFIELDS => $body,\n]);\n\n$data = json_decode(curl_exec($ch), true);\ncurl_close($ch);" } ], "x-discovery": [ "Tool names and their argument schemas \u2190 send {\"method\": \"tools/list\"} to this same endpoint; every tool mirrors the REST operation of the same name." ], "operationId": "mcpJsonRpc", "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": "JSON-RPC transport; the rate class and side effects depend on the tool called", "x-error-codes": [ "agency_agent_required", "agencypro_required", "api_access_disabled", "api_subscription_inactive", "api_write_operations_disabled", "attached_user_no_reports_permission", "cannot_cancel", "cannot_reissue", "client_not_owned", "credentials_in_query_string", "existing_account", "http_error", "idempotency_in_flight", "internal_error", "invalid_credentials", "method_not_allowed", "missing_credentials", "permission_denied", "profile_not_assigned", "provision_limit_reached", "rate_limited", "unsupported_campaign_type", "validation_failed", "workspace_access_denied", "workspace_required" ] } } } }