API Documentation
Make your first post in 60 seconds
Here is exactly what a request looks like. In the in-app version you can run it right here — it creates a draft, so nothing is published — and your draft lands in your Publisher, ready to review, edit or schedule.
Safe to try — it only ever creates a draft, never publishes1
This is what a request looks like. Replace
PASTE_YOUR_API_KEY_HERE with your own API key
in your tool's Authorization field. Nothing runs on this page, and you should never paste
a key into a web page — the in-app Console injects it for you instead.
Add a profile in your workspace settings and it will
appear in Your IDs.
POST https://www.sociamonials.com/api/v1/posts
Authorization: Bearer PASTE_YOUR_API_KEY_HERE
Content-Type: application/json
{
"mode": "draft",
"message": "Hello from the API - this is a draft, nothing is published.",
"networks": {
"fb": {
"profile_refs": [
"[your profile ID]"
]
}
}
}
2
Send it. We run the request with your account's key behind the
PASTE_YOUR_API_KEY_HERE — you never
have to paste or handle it here.
Activate your live API keys in the app to run this.
In the app, Send creates a real draft using your key (never shown in your browser) — nothing publishes.
3
Open your Publisher — your draft is waiting. When you're ready to automate for real, the
same request works from any tool below.
Want to build it in a tool? See Connectors for Make, Zapier, n8n, and AI assistants like Claude and ChatGPT. Need the full endpoint list? See API Reference.
API keys
API keys authenticate every request. Each key acts with a chosen user's permissions, profile access and approval routing. Keys are created and managed inside your account — they are never shown on this public page.
Sign in and open the API Console
to create, copy and manage your keys.
Who can create a key? API access is included with every paid and
lifetime plan at no extra cost — it is not sold separately. Free trials are
excluded: the Console opens but Create API Key sends you to choose a plan, and a
credential belonging to a trial, lapsed or suspended account returns
402 api_subscription_inactive. The Agency API
additionally requires an active AgencyPro subscription on the primary
agency workspace; without it that workspace gets the Workspace API instead.
While the API is in pre-launch, keys are being issued to preview accounts first.
Keep your keys safe. A key is shown only once, when you create or recycle
it — we store only a one-way hash and can never show it again. Paste a key only into a
tool's dedicated API-key, secret, or Authorization field. Never paste it into a chat
message, support ticket, screenshot, or document. If a key is exposed, revoke it and create
a new one.
Your IDs
These are the IDs your automations use to say where a post goes. None of these are secret — copy them freely into your tools.
Your real profile and workspace IDs appear here when you
sign in.
Social profile IDs
Paste a profile ID into the
profile_refs field to choose which profile a post publishes to.
| Network | Profile | Profile ID |
|---|---|---|
| Your Page | [your profile ID] | |
| Your Profile | [your profile ID] |
Workspace IDs
Agency accounts: paste a
workspace ID into workspace_registration_id (or the
workspaces list for bulk publishing) to choose which client
workspace a post belongs to. Signed-in agency owners see their full workspace roster here,
with a live search.
| Workspace | Workspace ID |
|---|---|
| Your client workspace | [your workspace ID] |
Rate limits & quotas
Every response tells you where you stand: your current limit is in the
X-RateLimit-Limit header (with X-RateLimit-Remaining and
X-RateLimit-Reset), and a 429 adds Retry-After.
Those headers are the source of truth; the numbers below are the defaults and may be
raised for your account.
Request rate limits (per API credential)
- Reads: 120 requests per minute.
- Writes: 30 requests per minute.
- Agency API agents: both rates are doubled.
- Identity and discovery endpoints are never rate limited. There are
exactly three:
GET /me,GET /workspacesandGET /workspaces/{workspaceId}/social-profiles. - The write limit counts requests, not posts. One
workspaces/publishcall can create posts in several workspaces while counting as a single write request.
Daily sending limits (per workspace, all sources)
These apply to every post a workspace sends, whether created through the API, the app, or CSV import.
- Up to 1,000 sent posts per day.
- Twitter / X: up to 100 tweets per day. Tweets cannot contain links. Enterprise workspaces may post up to 50 tweets containing links per month.
- Pinterest: up to 100 pins per day.
- YouTube: up to 10 uploads per channel per 24 hours (a YouTube platform rule; uploads above this hard-fail).
Resource quotas
- Posting queue: up to 1,500 undelivered posts per workspace, across all sources (API, app, CSV). Drafts never count.
- Scheduling horizon: publish times up to 12 months ahead.
- Video size: up to 1,024 MB per video.
- Analytics: date ranges up to 366 days per request.
- Client provisioning (AgencyPro): up to 25 new client workspaces per agency per day.
- Sweepstakes entries:
GET /sweepstakes/{id}/entriesreturns up to 200 entries per page. The API reads entries; it does not create them.
Connectors & Downloads
Ready-made ways to connect the API to the tools you already use — no-code blueprints for Make, n8n and Zapier, AI assistants over MCP — plus raw, importable spec files (OpenAPI, Postman, Power Automate).
No-code blueprints
Make.com blueprint
Import as a scenario: Scenarios → ⋯ → Import Blueprint. Pre-filled and ready to map.
Download blueprintn8n workflow
Import into n8n: Workflows → Import from File. Includes a Header Auth credential step.
Download workflowZapier
No prebuilt Zapier app — use Zapier's generic "Webhooks by Zapier → Custom Request" action with your API key as a bearer token.
Connect Make.com
Import the blueprint, paste your key over the placeholder, and run once — it creates a draft and publishes nothing.
- Download the blueprint and import it: Scenarios → ⋯ → Import Blueprint.
- Open the HTTP module's Authorization header, select everything in the Value field, and paste your API key over PASTE_YOUR_API_KEY_HERE. The key works with or without the word Bearer.
- Put your post text in message and paste a profile ID into profile_refs. Leave fields you don't need empty — they are ignored. Keep mode as draft and run once.
Your profile IDs are in Your IDs, on this page.
Connect n8n
Import the starter workflow, add one Header Auth credential, and run it — it creates a draft.
- Download the starter workflow and import it: Workflows → ⋯ → Import from File.
- Create the credential: Credentials → New → Header Auth. Name: Authorization, Value: Bearer PASTE_YOUR_API_KEY_HERE (with your key pasted in).
- Select that credential on both HTTP Request nodes, put your text in message, paste a profile ID into profile_refs, then run — it creates a draft post and publishes nothing.
n8n also has an MCP Client node: point it at https://www.sociamonials.com/api/mcp with the same Authorization header.
Connect Zapier
There is no published Zapier app for this API, so there is nothing to search for in Zapier's app directory. Instead you call the API directly with Zapier's built-in Webhooks by Zapier action — it works with every /api/v1 endpoint.
- Create an API key in API Keys and copy it once — you'll paste it in step 4.
- In your Zap, add an action step and pick Webhooks by Zapier, then choose the event Custom Request.
- Set Method to POST and URL to https://www.sociamonials.com/api/v1/posts.
- Under Headers, add two rows: Authorization = Bearer PASTE_YOUR_API_KEY_HERE (the key from step 1), and Content-Type = application/json.
- Set Data Pass-Through? to No, then paste your request into the Data field. This example creates a draft, so nothing publishes — your profile IDs are in Your IDs:{ "mode": "draft", "message": "Hello from the API - this is a draft, nothing is published.", "networks": { "fb": { "profile_refs": [ "[your profile ID]" ] } } }
- Click Test action. A 201 response with a post_id means it worked — your draft is waiting in your Publisher.
To publish for real, change "mode" to "scheduled" (with a publish_at) or "publish_now". See API Reference for every field.
AI Assistants & LLMs
Let Claude, ChatGPT or any MCP-capable assistant post for you. Add a ready-made connector below, connect over MCP, or paste the machine-readable reference straight into your assistant so it knows every endpoint.
ChatGPT Action — trimmed
For importing into a Custom GPT only. ChatGPT's Action importer accepts at most 30 operations, so this file is a deliberately reduced subset of the API — some operations, including parts of the agency and provisioning surface, are not in it. For everything else use the complete OpenAPI 3 spec in Downloads below.
Download GPT Action Connect Claude
Two ways in, and they work together: the packaged skill teaches Claude the safe workflow, and the MCP connector gives it the tools.
- Download the ready-made skill and add it to Claude (claude.ai → Settings → Capabilities → Skills, or your Claude Code skills folder).
- Or connect live over MCP — Claude Desktop → Settings → Connectors → Add custom connector:{ "mcpServers": { "social-api": { "type": "http", "url": "https://www.sociamonials.com/api/mcp", "headers": { "Authorization": "Bearer PASTE_YOUR_API_KEY_HERE" } } } }
- Tell Claude the safe workflow in your project instructions: create drafts by default, never publish unless asked, confirm the profiles, date, time and time zone first, and never repeat the credential back.
- Test it: ask Claude — “List my social profiles.”
The skill and the MCP connector can be used together: the skill teaches the workflow, MCP provides the tools. The server name is yours to choose — the packaged download uses your own brand's name.
Connect ChatGPT
Either connect over MCP, or import the GPT Action file into a Custom GPT.
- Connector: Settings → Connectors → Advanced → Developer mode → Create, then enter:MCP Server URL: https://www.sociamonials.com/api/mcp Header name: Authorization Header value: Bearer PASTE_YOUR_API_KEY_HERE Authentication: Custom headers (API key)
- Or build a Custom GPT: Configure → Actions → import this Action file, set Authentication to API Key, header name Authorization, value Bearer PASTE_YOUR_API_KEY_HERE. Note: ChatGPT's importer caps an Action at 30 operations, so this file is a trimmed subset — the connector route above (or the complete OpenAPI 3 spec in Downloads) covers the whole API.
- Put the safe workflow in the GPT or chat instructions: drafts by default, confirm profiles and times, never repeat the credential.
- Test it: ask — “List my social profiles.”
ChatGPT needs a connector type that supports a custom Authorization header; OAuth-only connectors will not work. Its Python sandbox has no internet, so the connector or the Action is the supported path.
Connect OpenAI Codex CLI
One block writes the config file for you; the credential stays in an environment variable, never in a config file.
- Download the Codex package (MCP config + AGENTS.md workflow guidance).
- Easiest: paste this one block into Terminal — it writes the Codex config file for you. These are the only lines here meant for the terminal:mkdir -p ~/.codex cat >> ~/.codex/config.toml << 'EOF' [mcp_servers.social-api] url = "https://www.sociamonials.com/api/mcp" bearer_token_env_var = "SM_API_CREDENTIAL" EOF
- Make your credential available to every terminal (zsh shown — use ~/.bash_profile if your prompt ends in $):echo 'export SM_API_CREDENTIAL="PASTE_YOUR_API_KEY_HERE"' >> ~/.zshrc && source ~/.zshrc
- Prefer doing it by hand? The server block above is TOML file content for ~/.codex/config.toml — do NOT paste it directly into the terminal (bash will say “command not found”).
- Drop the packaged AGENTS.md into your project so Codex follows the safe workflow (drafts by default, never publish without being asked).
- Test it: ask Codex — “List my social profiles.”
bearer_token_env_var keeps the credential out of config files entirely — Codex reads it from the environment at connect time.
Connect over MCP (Model Context Protocol)
Point any MCP-capable assistant at the endpoint below and add your API key as the bearer token in the assistant's own credential field. MCP runs on the same permissions as REST, so a tool can never do something the same credential could not do over HTTP.
Endpoint: https://www.sociamonials.com/api/mcp
Auth header: Authorization: Bearer PASTE_YOUR_API_KEY_HERE
MCP tools (31)
Every tool the MCP server exposes, with the permission it needs and exactly what it does. Protocol 2025-06-18 over streamable-http (JSON-RPC 2.0). Tools marked Agency need an Agency API credential; the rest work with either.
| Tool | Available to | Permission | What it does |
|---|---|---|---|
| get_api_agent_identity | Workspace + Agency | none - any active credential |
Who am I: agent id/type/name/status and current API access entitlement. No side effects. Requires: valid credential + active entitlement (all tools do; an ineligible or suspended account returns api_subscription_inactive). |
| get_api_agent_permissions | Workspace + Agency | none - any active credential |
Effective permissions per assigned workspace, including whether posting routes through human approval. No side effects. |
| list_assigned_workspaces | Workspace + Agency | none - any active credential |
Workspace ids this agent may operate in. Permissions differ per workspace — check get_api_agent_permissions. No side effects. |
| list_social_profiles | Workspace + Agency | profiles.read |
Connected social profiles in one workspace with capabilities and whether THIS agent may publish to each. Requires profiles.read in that workspace. Never returns third-party tokens. No side effects. |
| validate_social_post | Workspace + Agency | posts.create (validation only) |
SANDBOX: dry-run a post request through the FULL validation pipeline (permissions, profile grants, selection resolution, platform rules, queue and scheduling limits) WITHOUT creating anything. No side effects ever - safe to call freely. Returns valid, profile_resolution and warnings, or the same 403/422 a real call would produce. Use this before create_social_post when unsure. |
| create_social_post | Workspace + Agency | posts.create |
Create a DRAFT (default) social post. Requires posts.create. Side effect: a draft row visible in your account. Without posts.publish_direct any later scheduling routes through the existing human approval path. Set mode=queue to add it to the posting queue instead. Name-based options (category, watermark, hashtag_group, cta_group, post_preset, pinterest.board_name) resolve against saved items; unknown names come back as warnings, never hard failures. Null policy: for any optional field, null (or the literal string "null") is the same as omitting it - the documented default applies silently; unknown field names are ignored and reported in warnings with a did-you-mean hint. image_url (singular) is accepted as an alias of image_urls. |
| schedule_social_post | Workspace + Agency | posts.create + posts.schedule |
Schedule a post for delivery at publish_at (ISO-8601 UTC). Requires posts.create + posts.schedule. SIDE EFFECT: the platform WILL publish to real social profiles at that time unless the post needs approval (agents without posts.publish_direct submit for approval instead). Validation errors are returned per network. Idempotency: pass idempotency_key (replays return the ORIGINAL result incl. profile_resolution). |
| publish_social_post | Workspace + Agency | posts.create + posts.schedule |
Publish as soon as the delivery worker runs (usually within a minute). Same permissions/approval semantics as schedule_social_post. STRONG side effect: real posts on real profiles. |
| publish_to_workspaces | Agency | posts.create (checked per workspace) |
Agency bulk operation: one content payload to many workspaces. SIDE EFFECT: creates (and, per mode, schedules for real delivery) one post per workspace. Permissions evaluated independently per workspace; returns one result per workspace (created / pending_approval / failed+reason); one failure never undoes another workspace. Every create_social_post field applies here: a top-level value is shared across all targets, and the same key inside a workspaces[] entry overrides it for that workspace (entries are objects with workspace_registration_id; a bare id number is also accepted). Rate limits: counts as one write. Idempotency: pass idempotency_key. Null policy: for any optional field, null (or the literal string "null") is the same as omitting it - the documented default applies silently; unknown field names are ignored and reported in warnings with a did-you-mean hint. |
| get_post | Workspace + Agency | posts.read |
Post detail with per-network delivery status. Requires posts.read in the post's workspace. No side effects. |
| get_post_status | Workspace + Agency | posts.read |
Alias of get_post. No side effects. |
| cancel_scheduled_post | Workspace + Agency | posts.cancel |
Cancel an undelivered scheduled post. SIDE EFFECT: the post will not be delivered (non-destructive stop; the row is preserved). Requires posts.cancel. Delivered posts cannot be canceled. |
| get_post_analytics | Workspace + Agency | analytics.read |
Delivery attempt log and per-network status for one post (includes the full post view). Requires analytics.read on the workspace that owns the post (plus posts.read for the embedded view). The attempt log is failure-biased on several platforms — empty does not mean unattempted. No side effects. |
| get_workspace_analytics | Workspace + Agency | analytics.read |
Workspace delivery summary over a UTC window (defaults: last 30 days; date-validated and range-capped identically to REST). Requires analytics.read in that workspace. Metric definitions and freshness are embedded in the response. No side effects. |
| get_agency_analytics | Agency | analytics.read (per workspace) |
Cross-workspace delivery rollup restricted to workspaces where THIS agent holds analytics.read (permission-aware; unreadable workspaces are silently excluded), ranked by dispatched posts. Window rules identical to get_workspace_analytics. No side effects. |
| get_published_messages_report | Workspace + Agency | analytics.read |
The Published Messages report - the in-app Reports screen as an API, one row per published message with the same columns: publisher, published_at_utc, message, per-network targeting flags, links, clicks, gbp_clicks, leads, sales, revenue (numeric USD), likes, comments, and 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, and a workspace with none configured returns an empty array). Filters mirror the screen: date_range (all | last_30_days default | last_60_days | last_90_days) OR from_utc/to_utc custom range (custom wins if both sent); networks[] (the checkbox row - omitted means all ten); post_id (single message); category_id; limit (1-200, default 50) / offset. IMPORTANT semantics stated in meta: click/conversion counts are LIFETIME per message (the date range selects which messages appear); network flags are compose-time targeting, not delivery; likes/comments are cached counters with no Twitter/X engagement. Requires analytics.read. No side effects. |
| get_campaigns_report | Workspace + Agency | analytics.read |
The Campaigns report - 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: name, campaign_type (numeric product type) + campaign_type_label (the template name the screen shows, null when that template is gone), created_at_utc, promoted_link (screen parity - null for several products including every viral sweepstakes) + campaign_link (the campaign public link that actually works), views, engagements, shares, referred_visits, leads, sales, revenue (numeric USD), referral_rewards, and the workspace-defined custom_conversions. Filters: date_range (all | last_30_days default | last_60_days | last_90_days) OR from_utc/to_utc custom range; date_field (views = screen parity, a range returns only campaigns VIEWED in the window, so a campaign created inside it but never viewed does not appear | created = filter on creation date); campaign_id; limit (1-200, default 50) / offset. This is REPORTING only - creating and managing campaigns through this API is still V2 Viral Sweepstakes only. Requires analytics.read. No side effects. |
| create_viral_sweepstakes | Workspace + Agency | sweepstakes.create |
Create a V2 Viral Sweepstakes as a DRAFT (set publish=true to go live immediately). SIDE EFFECT: creates a campaign and its public short link. Requires sweepstakes.create. ONLY four fields are required - title, description, grand_prize_name, grand_prize_description; rules, winner selection, emails, dates and challenges are auto-filled from the same template defaults as the UI. Optional: theme (the name or id of a Campaign Theme - call list_sweepstakes_themes to see the choices; omit for the default look), base_campaign (the name or id of one of YOUR OWN campaigns to clone as the template - look AND behavior travel, prizes/dates/identity come from this request; source is the agency primary workspace for agency credentials or this workspace for workspace credentials; call list_sweepstakes_base_campaigns to see the choices; cannot be combined with theme), grand_prize_image_url, background_image_url (https image used as the campaign page background, applied with the editor defaults - image not repeated, black overlay at 0% opacity), additional_prizes[], opt_in (single or double; omitted = inherit the theme/base_campaign value when one is applied, else single), entry_form (plain name of a saved entry form in the workspace; call list_sweepstakes_entry_forms to see names), settings{} (any Settings-tab control), start_date/end_date, publish. bonus_challenges[] adds Bonus Entry Challenges - extra actions worth more entries. Each needs type (button | button_question | question | refer_friends), label and entries; the rest depends on type - button_url/button_text for button types, question (+ question_type open-ended|multiple-choice and choices[]) for question types, share_message and referral_tracks (visits|sales|leads) for refer_friends. Optional per challenge: platform, description, enabled, icon, icon_color, repeat_every, accepted_answers[]. Display order follows the array order and cannot be set. Contests and legacy campaign builders are NOT supported. Null policy: for any optional field, null (or the literal string "null") is the same as omitting it - the documented default applies silently; unknown field names are ignored and reported in warnings with a did-you-mean hint. |
| list_sweepstakes_entry_forms | Workspace + Agency | sweepstakes.read |
List the saved entry forms in this workspace by plain-English name (e.g. Default, Phone, Family Contest) with their ids and which is the default. Use a name as the entry_form when creating a sweepstakes. Requires sweepstakes.read. No side effects. |
| list_sweepstakes_base_campaigns | Workspace + Agency | sweepstakes.read |
List the campaigns usable as a base_campaign template when creating a Viral Sweepstakes. The source workspace is fixed by credential type - the agency primary workspace for agency credentials, this workspace for workspace credentials - so no workspace argument is taken; requires sweepstakes.read on that source workspace. Draft and paused campaigns are valid bases. No side effects. |
| list_sweepstakes_themes | Workspace + Agency | sweepstakes.read |
List the Campaign Themes available for a Viral Sweepstakes (the V2-enabled themes shown in the UI theme picker) by plain-English name with their ids and whether each is premium. Use a name or id as the theme when creating a sweepstakes. Requires sweepstakes.read. No side effects. |
| get_viral_sweepstakes | Workspace + Agency | sweepstakes.read |
Full Sweepstakes-Console detail for one V2 Viral Sweepstakes incl. public link, prizes, official rules, and all settings. Requires sweepstakes.read. No side effects. |
| get_viral_sweepstakes_results | Workspace + Agency | sweepstakes.read |
Entry/visit/share/winner totals for a V2 Viral Sweepstakes. Requires sweepstakes.read. No side effects. |
| get_viral_sweepstakes_entries | Workspace + Agency | sweepstakes.read |
Paginated entrant list from the Sweepstakes Console. Requires sweepstakes.read. No side effects. |
| provision_client_workspace | Agency | clients.provision (AgencyPro) |
AGENCY + AgencyPro only. Provision a NEW client workspace under one of your Pricing Plans WITHOUT charging (the plan price is ignored). Requires clients.provision. Pass the plan (name or id) + the customer's contact info; returns an onboarding_url (7-day, single-use) that drops the customer into set-password + the plan's onboarding screens — the account itself is created when they open the link. No password is accepted here (set at handoff). If the email already has an account you get existing_account (409). Daily cap per agency applies. SIDE EFFECT: records a provision request and issues a link; the real account is created at handoff. |
| get_client_provision_status | Agency | clients.provision (AgencyPro) |
Check a provision request: returns status (pending|redeemed) and, once the customer has completed onboarding, the workspace_registration_id. No side effects. |
| get_client_login_link | Agency | clients.provision (AgencyPro) |
AGENCY + AgencyPro only. Mint a short-lived (~10 min), single-use sign-in link for an EXISTING client workspace you provisioned, so a user in your app can jump straight into their social workspace. Requires clients.provision. Scoped: only works for workspaces linked to your agency. SIDE EFFECT: issues a one-time sign-in link (no data changes). |
| pause_client_workspace | Agency | clients.provision (AgencyPro) |
AGENCY + AgencyPro only. Temporarily PAUSE a client workspace you provisioned: the client can no longer sign in and the workspace is hidden in the agency dashboard; scheduled data is untouched. Reversible with resume_client_workspace. Requires clients.provision. SIDE EFFECT: blocks a real client's access. |
| resume_client_workspace | Agency | clients.provision (AgencyPro) |
Reverse of pause_client_workspace: re-enables sign-in and dashboard visibility. Requires clients.provision. SIDE EFFECT: restores a client's access. |
| delete_client_workspace
destructive
|
Agency | clients.provision (AgencyPro) |
AGENCY + AgencyPro only. DELETE a client workspace: PERMANENT and IRREVERSIBLE — the account is flagged deleted platform-wide, unlinked from the agency, and sign-in is disabled forever. There is NO undelete; if you only want to block access temporarily, use pause_client_workspace instead. Requires clients.provision. Two-step by design (SEC-24): a first call without confirm:true is REFUSED with a validation error — only a deliberate confirm:true actually deletes. DESTRUCTIVE SIDE EFFECT. |
| get_viral_sweepstakes_promote_assets | Workspace + Agency | sweepstakes.read |
Get OPT-IN Promote assets for a sweepstakes: ready-to-paste JavaScript embed snippets (iframe, button, stickytab, popup) and/or a QR-code image URL. Nothing is returned unless requested. embeds[] picks snippet types; options{} sets per-type slide-in settings (fly_in_effect, only_on_first_visit, delay_seconds, position, title); qr:true returns a QR image URL for print signs. Ideal for an AI building a website that wants to drop in a sweepstakes popup. Side effect: persists the chosen slide-in options to the campaign so the rendered embed honors them. Requires sweepstakes.read. |
API Reference for LLMs
Machine-readable reference for AI agents and LLM integrations. Copy and paste it into your assistant so it understands every endpoint. It contains no credential — and you should never paste your API key into a chat.
Where does the key go? Into your tool's own
credential or header field — never into the request body.
Raw spec files are below, or see
API reference for full field tables,
code samples and the errors each endpoint can return.
Downloads — specs & collections
Raw, importable definitions of the API — drop them into any client, code generator or connector platform.
OpenAPI 3 spec — complete
The full definition: 32 operations, with this domain already substituted. This is the canonical spec — use it for any client, code generator or connector platform.
Download OpenAPI specPostman collection
Every endpoint as a Postman request, base URL and key as variables.
Download collectionPower Automate connector
A Swagger 2.0 custom-connector definition for Power Automate.
Download connector Connect Postman
Every endpoint as a request, with the base URL and the key as collection variables.
- Download the collection and import it into Postman.
- Set the apiKey collection variable to your credential. baseUrl is already set to https://www.sociamonials.com.
- Start with GET /api/v1/me — it is rate-limit exempt and confirms the key and its permissions in one call.
Connect Power Automate
A Swagger 2.0 custom-connector definition — the format Power Automate imports.
- Download the connector definition.
- Data → Custom connectors → New custom connector → Import an OpenAPI file, and pick the download.
- Security is preconfigured as API Key on the Authorization header. When a flow first uses the connector, enter: Bearer PASTE_YOUR_API_KEY_HERE (with your key pasted in).
API Reference
Every endpoint, with live examples. Send your key as Authorization: Bearer <key> — the Bearer prefix is optional. Read requests run right here with your key injected securely; nothing is ever shown or published.
Testing here only reads data or creates drafts — it never publishes and never shows your keyNeed a ready-made blueprint or an importable spec? See Connectors & Downloads for Make, n8n, Zapier, AI assistants, the LLM reference, and the OpenAPI spec / Postman / Power Automate downloads.
Troubleshoot an error
Hit a wall in your AI agent or workflow tool? Paste the error and we'll tell you what it means and how to fix it.
Credentials, tokens and personal details are removed before analysis — in your browser first, then again on the server. Nothing is run or published.
Analyze (nothing is executed)
The error analyzer runs in the in-app version. Sign in to use it.
Want the full list of codes and what to do about each one? See the Error reference.
Error reference
Every failure returns the same JSON shape, with a stable machine-readable code, a human message, and a request_id to quote if you contact support. Match on code, never on the message text.
{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid.",
"request_id": "9f1c...",
"errors": { "message": "is required" }
}
}
errors is present only on validation_failed, where it maps each field to its own problem. Rate-limited responses also carry Retry-After and the X-RateLimit-* headers.
| HTTP | error.code | What it means | What to do |
|---|---|---|---|
| 400 | credentials_in_query_string | The key was sent as a ?token=, ?api_key= or ?access_token= query parameter. That exposes it in logs and browser history, so the request is refused and the exposure is recorded. |
Move the key into the Authorization header: Authorization: Bearer <key>. Then recycle that key — treat it as exposed. |
| 401 | missing_credentials | No Authorization header reached the API. |
Send Authorization: Bearer <key>. In no-code tools this is the connection or Header Auth credential, not a body field. Some proxies strip the header — check your tool's header settings. |
| 401 | invalid_credentials | The credential is not valid. Unknown, revoked and expired keys are deliberately indistinguishable. |
Confirm you pasted the whole key with no leading or trailing space. The Bearer prefix is optional — both forms authenticate identically. If the key was revoked or recycled, create a new one in the Console. |
| 402 | api_subscription_inactive | The credential is valid, but API access is not active for this account — it is on a free trial, or its plan has lapsed or been suspended. API access is not sold separately - it is included with every paid and lifetime plan. |
The account owner activates a paid plan; API access follows automatically. Agency API credentials additionally need an active AgencyPro subscription — without it the message says so, and a Workspace API credential still works. |
| 403 | permission_denied | The credential authenticated, but this API Agent has not been granted the permission the operation needs (for example posts.publish_direct, analytics.read or clients.provision). |
Call GET /api/v1/me — it returns the full per-workspace permission map. Grant the missing permission to the agent, or use an operation you are allowed to call (for example create for approval instead of publishing directly). |
| 403 | workspace_access_denied | The workspace exists but this API Agent is not assigned to it. |
Use GET /api/v1/workspaces to list the workspaces the credential can reach, or assign the workspace to the agent. |
| 403 | profile_not_assigned | You named a social profile in networks.<code>.profile_refs that this API Agent — or the user the credential is attached to — is not assigned to in that workspace. This is the most common first-integration failure. |
List the workspace's profiles with GET /workspaces/{workspaceId}/social-profiles and use only those whose agent_can_publish_to is true. A profile that arrives via a post_preset is dropped with a warning for attached-user agents, but a profile you name explicitly always hard-fails. |
| 403 | attached_user_no_reports_permission | This credential is attached to a workspace user, and that user does not hold the "Access Reports" permission that analytics requires. |
Grant "Access Reports" to that user in Workspace Users, then retry. Or use a credential that is not restricted to that user. |
| 403 | agency_agent_required | Client provisioning and the client lifecycle operations need an Agency API Agent. The credential you used is a Workspace API Agent. |
Use an Agency API credential from the primary agency workspace. That workspace needs an active AgencyPro subscription to be an Agency API account at all. |
| 403 | agencypro_required | The credential is an Agency API Agent, but client provisioning is an AgencyPro feature and this agency does not have an active AgencyPro subscription. |
Reactivate AgencyPro on the agency. Publishing, sweepstakes and analytics for workspaces you already operate are unaffected. |
| 403 | client_not_owned | The workspace you targeted is not a client of this agency — or you aimed a client-lifecycle operation at the agency's own account, which is never allowed. |
GET /workspaces lists the client workspaces this credential can operate. The agency's own workspace can never be paused, resumed or deleted through client lifecycle. |
| 403 | provision_limit_reached | This agency has already provisioned its daily maximum of new client workspaces. |
Retry tomorrow, or have an administrator raise the per-agency daily provisioning limit. The message names the current cap. |
| 403 | api_write_operations_disabled | The administrator has turned the API write kill-switch on. Reads keep working; anything that would change data is refused. |
Nothing to change in your integration — retry once writes are re-enabled. Read endpoints are unaffected. |
| 404 | not_found | The post, job, sweepstakes or provisioning record does not exist, or it is not in a workspace this credential can read. |
Re-check the id, and check the workspace: an id from another workspace looks exactly like a missing one. |
| 405 | method_not_allowed | The path is right and the method is wrong — the route exists for a different verb. |
Check the method against the endpoint list on the left. Reading a post is GET /posts/{id}; cancelling it is DELETE /posts/{id}. |
| 409 | existing_account | The email you passed to client provisioning already has an account. Attaching an existing account to an agency is not supported yet. |
Provision with an email that has no account. An existing workspace has to be linked to the agency outside the API. |
| 409 | idempotency_in_flight | A request carrying this idempotency_key is already being processed. This is the guard that stops a retry creating a second post. |
Wait a moment and retry the same key — you will collect the original result rather than create a duplicate. |
| 409 | cannot_cancel | The post is no longer in a state that can be cancelled (it has already been sent, or already cancelled). |
Read the post first and cancel only while it is still pending. |
| 409 | cannot_reissue | The provisioning handoff link cannot be reissued in its current state. |
Read the provisioning record for its current state before reissuing. |
| 422 | validation_failed | The request reached the platform's validation pipeline and one or more fields were rejected. error.errors maps each field to its own problem. |
Fix the named fields. This is the code a dry-run returns too, so you can validate without creating anything. |
| 422 | workspace_required | This credential could not be matched to a single workspace, so the API cannot tell which one the call should act on. |
Pass workspace_registration_id. GET /workspaces lists the ones this credential can use. |
| 422 | unsupported_campaign_type | The campaign you referenced is not a V2 Viral Sweepstakes. The API only supports V2 Viral Sweepstakes — never contests or the legacy campaign builders. |
Target a V2 Viral Sweepstakes, or create one with the sweepstakes endpoints. |
| 429 | rate_limited | The credential exceeded its per-minute read or write limit. |
Wait for Retry-After seconds. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are on every response, so you can pace requests instead of retrying blind. |
| 500 | internal_error | An unexpected failure on the platform side, not a problem with your request. |
Retry — this class of failure is treated as transient. If it persists, contact support and quote the request_id from the response. |
| 503 | api_access_disabled | The API is switched off platform-wide by the administrator. This is not about your account or your key. |
Retry later; no change to your integration is needed. |
| 4xx / 5xx | http_error | The request failed at the HTTP layer before any endpoint logic could classify it — a malformed request, an unsupported media type, a request that never reached a controller. The response status tells you which. |
Check the URL, method, headers and body encoding. If the same status keeps coming back, contact support and quote the request_id. |
Each endpoint lists the subset it can return — see the Errors table on any endpoint in the API Reference. Pasting a raw error into Troubleshoot will match it for you.