{ "swagger": "2.0", "info": { "title": "Sociamonials API", "version": "1.0.0", "description": "Custom connector. In Power Automate: Custom connectors, New custom connector, Import an OpenAPI file, then pick this file. On the Security tab choose API Key, parameter label and name Authorization, location Header, and paste your API key as the value (the \"Bearer \" prefix is optional). Create a key at https://www.sociamonials.com/login.php?redirect=accounts%2Fapi_keys.php (sign in first, then Create API Key). Test the connector with GET /api/v1/me before you build a flow. Full reference: https://www.sociamonials.com/developers.php." }, "host": "www.sociamonials.com", "basePath": "/", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "securityDefinitions": { "api_key": { "type": "apiKey", "in": "header", "name": "Authorization" } }, "security": [ { "api_key": [] } ], "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.", "operationId": "getMe", "responses": { "200": { "description": "Identity", "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "product_label": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" } } }, "credential": { "type": "object", "properties": { "name": { "type": "string" }, "token_prefix": { "type": "string" }, "expires_at": { "type": "string" } } }, "entitlement": { "type": "object", "properties": { "state": { "type": "string" }, "source": { "type": "string" }, "source_label": { "type": "string" } } }, "workspaces": { "type": "object" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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.", "operationId": "listWorkspaces", "responses": { "200": { "description": "Workspaces", "schema": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "name": { "type": "string" }, "company": { "type": "string" }, "display_name": { "type": "string" }, "permissions": { "type": "object", "properties": { "posts.create": { "type": "boolean" } } }, "requires_approval_for_posting": { "type": "boolean" } } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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.", "operationId": "listSocialProfiles", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "type": "integer", "description": "Workspace registration id (GET /api/v1/workspaces)", "x-ms-summary": "Workspace ID" } ], "responses": { "200": { "description": "Profiles", "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string" }, "network_name": { "type": "string" }, "profile_ref": { "type": "string" }, "name": { "type": "string" }, "agent_can_publish_to": { "type": "boolean" } } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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 ...", "operationId": "createPost", "parameters": [ { "name": "body", "in": "body", "required": true, "x-ms-summary": "Request body", "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" ] } } ], "responses": { "201": { "description": "Created", "schema": { "type": "object", "properties": { "post_id": { "type": "integer" }, "status": { "type": "string" }, "requires_approval": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "getPost", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "post_id returned by POST /api/v1/posts", "x-ms-summary": "ID" } ], "responses": { "200": { "description": "Post", "schema": { "type": "object", "properties": { "post_id": { "type": "integer" }, "workspace_registration_id": { "type": "integer" }, "message": { "type": "string" }, "publish_date_utc": { "type": "string" }, "draft": { "type": "boolean" }, "canceled": { "type": "boolean" }, "approved": { "type": "boolean" }, "delivered": { "type": "boolean" }, "networks": { "type": "object", "properties": { "fb": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "delivered": { "type": "boolean" }, "delivery_status": { "type": "string" }, "error": { "type": "string" } } }, "tw": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "delivered": { "type": "boolean" }, "delivery_status": { "type": "string" }, "error": { "type": "string" } } } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } }, "delete": { "summary": "Cancel a scheduled post", "description": "Non-destructive cancel; already-delivered posts cannot be canceled (409).", "operationId": "cancelPost", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "post_id to cancel", "x-ms-summary": "ID" } ], "responses": { "200": { "description": "Canceled", "schema": { "type": "object", "properties": { "post_id": { "type": "integer" }, "status": { "type": "string" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "publishToWorkspaces", "parameters": [ { "name": "body", "in": "body", "required": true, "x-ms-summary": "Request body", "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" ] } } ], "responses": { "200": { "description": "Accepted", "schema": { "type": "object", "properties": { "job_id": { "type": "integer" }, "status": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "status": { "type": "string" }, "post_id": { "type": "integer" } } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/api/v1/jobs/{id}": { "get": { "summary": "Bulk job status", "description": "Progress and per-workspace results of a bulk publish job.", "operationId": "getJob", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "job_id from POST /api/v1/workspaces/publish", "x-ms-summary": "ID" } ], "responses": { "200": { "description": "Job", "schema": { "type": "object", "properties": { "job_id": { "type": "integer" }, "status": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "post_id": { "type": "integer" } } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "getWorkspaceAnalytics", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "type": "integer", "description": "Workspace registration id", "x-ms-summary": "Workspace ID" }, { "name": "from_utc", "in": "query", "required": false, "type": "string", "description": "ISO-8601 UTC start (default: 30 days ago)", "x-ms-summary": "From UTC" }, { "name": "to_utc", "in": "query", "required": false, "type": "string", "description": "ISO-8601 UTC end (default: now)", "x-ms-summary": "To UTC" } ], "responses": { "200": { "description": "Metrics", "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "window": { "type": "object", "properties": { "from_utc": { "type": "string" }, "to_utc": { "type": "string" }, "timezone": { "type": "string" } } }, "totals": { "type": "object", "properties": { "posts_created": { "type": "integer" }, "posts_delivered": { "type": "integer" }, "posts_pending": { "type": "integer" }, "drafts": { "type": "integer" }, "canceled": { "type": "integer" } } }, "by_network": { "type": "object", "properties": { "fb": { "type": "object", "properties": { "network_name": { "type": "string" }, "posts_targeted": { "type": "integer" }, "posts_delivered": { "type": "integer" } } } } }, "meta": { "type": "object", "properties": { "metric_definitions": { "type": "object" }, "timezone": { "type": "string" } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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 ...", "operationId": "getPublishedMessages", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "type": "integer", "description": "Workspace registration id", "x-ms-summary": "Workspace ID" }, { "name": "date_range", "in": "query", "required": false, "type": "string", "description": "The screen presets; ignored when from_utc/to_utc are sent", "x-ms-summary": "Date Range" }, { "name": "from_utc", "in": "query", "required": false, "type": "string", "description": "ISO-8601 UTC start (Custom Range)", "x-ms-summary": "From UTC" }, { "name": "to_utc", "in": "query", "required": false, "type": "string", "description": "ISO-8601 UTC end (Custom Range)", "x-ms-summary": "To UTC" }, { "name": "networks", "in": "query", "required": false, "type": "string", "description": "comma list of facebook,linkedin,twitter,youtube,instagram,bluesky,gbp,pinterest,tiktok,threads - omitted = all ten (the screen default)", "x-ms-summary": "Networks" }, { "name": "post_id", "in": "query", "required": false, "type": "integer", "description": "restrict to one message", "x-ms-summary": "Post ID" }, { "name": "category_id", "in": "query", "required": false, "type": "integer", "description": "the screen's Categories dropdown (post category id)", "x-ms-summary": "Category ID" }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "Page size", "x-ms-summary": "Limit" }, { "name": "offset", "in": "query", "required": false, "type": "integer", "description": "Pagination offset", "x-ms-summary": "Offset" } ], "responses": { "200": { "description": "Report", "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "window": { "type": "object", "properties": { "from_utc": { "type": "string" }, "to_utc": { "type": "string" }, "timezone": { "type": "string" }, "all_dates": { "type": "boolean" } } }, "filters": { "type": "object", "properties": { "networks": { "type": "array", "items": { "type": "string" } }, "category_id": { "type": "string" }, "post_id": { "type": "string" } } }, "total": { "type": "integer" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "post_id": { "type": "integer" }, "published_by": { "type": "string" }, "published_at_utc": { "type": "string" }, "message": { "type": "string" }, "networks": { "type": "object", "properties": { "facebook": { "type": "integer" }, "twitter": { "type": "integer" } } }, "links": { "type": "array", "items": { "type": "string" } }, "clicks": { "type": "integer" }, "gbp_clicks": { "type": "integer" }, "leads": { "type": "integer" }, "sales": { "type": "integer" }, "revenue": { "type": "number" }, "currency": { "type": "string" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "custom_conversions": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string" }, "name": { "type": "string" }, "count": { "type": "integer" } } } } } } }, "meta": { "type": "object" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "getCampaignsReport", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "type": "integer", "description": "Workspace registration id", "x-ms-summary": "Workspace ID" }, { "name": "date_range", "in": "query", "required": false, "type": "string", "description": "The screen presets; ignored when from_utc/to_utc are sent", "x-ms-summary": "Date Range" }, { "name": "from_utc", "in": "query", "required": false, "type": "string", "description": "ISO-8601 UTC start (custom range)", "x-ms-summary": "From UTC" }, { "name": "to_utc", "in": "query", "required": false, "type": "string", "description": "ISO-8601 UTC end (custom range)", "x-ms-summary": "To UTC" }, { "name": "date_field", "in": "query", "required": false, "type": "string", "description": "views = screen parity (a range returns only campaigns VIEWED in the window); created = filter on creation date", "x-ms-summary": "Date Field" }, { "name": "campaign_id", "in": "query", "required": false, "type": "integer", "description": "restrict to one campaign", "x-ms-summary": "Campaign ID" }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "Page size", "x-ms-summary": "Limit" }, { "name": "offset", "in": "query", "required": false, "type": "integer", "description": "Pagination offset", "x-ms-summary": "Offset" } ], "responses": { "200": { "description": "Report", "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "window": { "type": "object", "properties": { "from_utc": { "type": "string" }, "to_utc": { "type": "string" }, "timezone": { "type": "string" }, "all_dates": { "type": "boolean" }, "date_field": { "type": "string" } } }, "filters": { "type": "object", "properties": { "campaign_id": { "type": "string" } } }, "total": { "type": "integer" }, "campaigns": { "type": "array", "items": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "name": { "type": "string" }, "campaign_type": { "type": "integer" }, "campaign_type_label": { "type": "string" }, "created_at_utc": { "type": "string" }, "promoted_link": { "type": "string" }, "campaign_link": { "type": "string" }, "views": { "type": "integer" }, "engagements": { "type": "integer" }, "shares": { "type": "integer" }, "referred_visits": { "type": "integer" }, "leads": { "type": "integer" }, "sales": { "type": "integer" }, "revenue": { "type": "number" }, "currency": { "type": "string" }, "referral_rewards": { "type": "integer" }, "custom_conversions": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string" }, "name": { "type": "string" }, "count": { "type": "integer" } } } } } } }, "meta": { "type": "object" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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.", "operationId": "getAgencyAnalytics", "parameters": [ { "name": "from_utc", "in": "query", "required": false, "type": "string", "description": "ISO-8601 UTC start (default: 30 days ago)", "x-ms-summary": "From UTC" }, { "name": "to_utc", "in": "query", "required": false, "type": "string", "description": "ISO-8601 UTC end (default: now)", "x-ms-summary": "To UTC" } ], "responses": { "200": { "description": "Metrics", "schema": { "type": "object", "properties": { "window": { "type": "object", "properties": { "from_utc": { "type": "string" }, "to_utc": { "type": "string" }, "timezone": { "type": "string" } } }, "workspaces_ranked_by_delivered": { "type": "array", "items": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "totals": { "type": "object" }, "by_network": { "type": "object" } } } }, "meta": { "type": "object" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "getPostAnalytics", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "post_id", "x-ms-summary": "ID" } ], "responses": { "200": { "description": "Metrics", "schema": { "type": "object", "properties": { "post_id": { "type": "integer" }, "delivery_attempts": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "response_code": { "type": "integer" }, "attempted_at_utc": { "type": "string" } } } }, "post": { "type": "object" }, "meta": { "type": "object" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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.", "operationId": "createSweepstakes", "parameters": [ { "name": "body", "in": "body", "required": true, "x-ms-summary": "Request body", "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" ] } } ], "responses": { "201": { "description": "Created", "schema": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "campaign_type": { "type": "integer" }, "product": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "theme": { "type": "string" }, "base_campaign": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "short_url": { "type": "string" }, "sweepstakes_link": { "type": "string" }, "publish_to_social": { "type": "string" }, "entry_form": { "type": "object", "properties": { "name": { "type": "string" }, "submission_form_id": { "type": "integer" }, "opt_in": { "type": "string" } } }, "grand_prize": { "type": "object", "properties": { "rank": { "type": "integer" }, "name": { "type": "string" }, "image": { "type": "string" }, "is_grand_prize": { "type": "boolean" } } }, "prizes": { "type": "array", "items": { "type": "string" } }, "official_rules_html": { "type": "string" }, "settings": { "type": "object" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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.", "operationId": "listSweepstakesEntryForms", "parameters": [ { "name": "workspace_registration_id", "in": "query", "required": false, "type": "integer", "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.", "x-ms-summary": "Workspace Registration ID" } ], "responses": { "200": { "description": "Forms", "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "entry_forms": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "submission_form_id": { "type": "integer" }, "is_default": { "type": "boolean" } } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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).", "operationId": "listSweepstakesThemes", "parameters": [ { "name": "workspace_registration_id", "in": "query", "required": false, "type": "integer", "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.", "x-ms-summary": "Workspace Registration ID" } ], "responses": { "200": { "description": "Themes", "schema": { "type": "object", "properties": { "themes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "premium": { "type": "boolean" } } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "listSweepstakesBaseCampaigns", "responses": { "200": { "description": "Base campaigns", "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "base_campaigns": { "type": "array", "items": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" } } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/api/v1/sweepstakes/{id}": { "get": { "summary": "Get a sweepstakes", "description": "Full Sweepstakes-Console view of one campaign.", "operationId": "getSweepstakes", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "campaign_id from POST /api/v1/sweepstakes", "x-ms-summary": "ID" }, { "name": "workspace_registration_id", "in": "query", "required": false, "type": "integer", "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.", "x-ms-summary": "Workspace Registration ID" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "campaign_type": { "type": "integer" }, "product": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "theme": { "type": "string" }, "base_campaign": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" }, "short_url": { "type": "string" }, "sweepstakes_link": { "type": "string" }, "publish_to_social": { "type": "string" }, "entry_form": { "type": "object", "properties": { "name": { "type": "string" }, "submission_form_id": { "type": "integer" }, "opt_in": { "type": "string" } } }, "grand_prize": { "type": "object", "properties": { "rank": { "type": "integer" }, "name": { "type": "string" }, "image": { "type": "string" }, "is_grand_prize": { "type": "boolean" } } }, "prizes": { "type": "array", "items": { "type": "string" } }, "official_rules_html": { "type": "string" }, "settings": { "type": "object" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/api/v1/sweepstakes/{id}/entries": { "get": { "summary": "List entries", "description": "Paged entrant list (limit/offset query params, default 50).", "operationId": "listSweepstakesEntries", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "campaign_id from POST /api/v1/sweepstakes", "x-ms-summary": "ID" }, { "name": "workspace_registration_id", "in": "query", "required": false, "type": "integer", "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.", "x-ms-summary": "Workspace Registration ID" }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "Page size", "x-ms-summary": "Limit" }, { "name": "offset", "in": "query", "required": false, "type": "integer", "description": "Page offset", "x-ms-summary": "Offset" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } } } }, "total": { "type": "integer" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/api/v1/sweepstakes/{id}/referrals": { "get": { "summary": "List referrers", "description": "Per-entrant referral tallies.", "operationId": "listSweepstakesReferrals", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "campaign_id from POST /api/v1/sweepstakes", "x-ms-summary": "ID" }, { "name": "workspace_registration_id", "in": "query", "required": false, "type": "integer", "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.", "x-ms-summary": "Workspace Registration ID" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "referrers": { "type": "array", "items": { "type": "object", "properties": { "crm_id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } } } }, "total_referrers": { "type": "integer" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/api/v1/sweepstakes/{id}/results": { "get": { "summary": "Results summary", "description": "Status, totals and winner state.", "operationId": "getSweepstakesResults", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "campaign_id from POST /api/v1/sweepstakes", "x-ms-summary": "ID" }, { "name": "workspace_registration_id", "in": "query", "required": false, "type": "integer", "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.", "x-ms-summary": "Workspace Registration ID" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "status": { "type": "string" }, "total_entries": { "type": "integer" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/api/v1/sweepstakes/{id}/pause": { "post": { "summary": "Pause a sweepstakes", "description": "Pauses a live campaign.", "operationId": "pauseSweepstakes", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "campaign_id from POST /api/v1/sweepstakes", "x-ms-summary": "ID" }, { "name": "workspace_registration_id", "in": "query", "required": false, "type": "integer", "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.", "x-ms-summary": "Workspace Registration ID" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "status": { "type": "string" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/api/v1/sweepstakes/{id}/duplicate": { "post": { "summary": "Duplicate a sweepstakes", "description": "Copies a campaign as a new draft.", "operationId": "duplicateSweepstakes", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "campaign_id from POST /api/v1/sweepstakes", "x-ms-summary": "ID" }, { "name": "workspace_registration_id", "in": "query", "required": false, "type": "integer", "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.", "x-ms-summary": "Workspace Registration ID" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "status": { "type": "string" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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.", "operationId": "promoteSweepstakes", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "campaign_id", "x-ms-summary": "ID" }, { "name": "workspace_registration_id", "in": "query", "required": false, "type": "integer", "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.", "x-ms-summary": "Workspace Registration ID" }, { "name": "body", "in": "body", "required": true, "x-ms-summary": "Request body", "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": [] } } ], "responses": { "200": { "description": "Assets", "schema": { "type": "object", "properties": { "sweepstakes_link": { "type": "string" }, "embeds": { "type": "object", "properties": { "button": { "type": "string" } } }, "qr": { "type": "object", "properties": { "image_url": { "type": "string" }, "external_url": { "type": "string" }, "target": { "type": "string" }, "stored": { "type": "boolean" } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "provisionClientWorkspace", "parameters": [ { "name": "body", "in": "body", "required": true, "x-ms-summary": "Request body", "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" ] } } ], "responses": { "201": { "description": "Provisioned", "schema": { "type": "object", "properties": { "provision_id": { "type": "integer" }, "onboarding_url": { "type": "string" }, "expires_at": { "type": "string" }, "missing_required_fields": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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.", "operationId": "getClientProvisionStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "provision_id from POST /workspaces/provision", "x-ms-summary": "ID" } ], "responses": { "200": { "description": "Status", "schema": { "type": "object", "properties": { "provision_id": { "type": "integer" }, "status": { "type": "string" }, "workspace_registration_id": { "type": "integer" }, "pricing_plan": { "type": "string" }, "email": { "type": "string" }, "missing_required_fields": { "type": "array", "items": { "type": "object" } }, "expires_at": { "type": "string" }, "redeemed_at": { "type": "string" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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.", "operationId": "reissueClientOnboardingLink", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "provision_id", "x-ms-summary": "ID" } ], "responses": { "200": { "description": "Reissued", "schema": { "type": "object", "properties": { "provision_id": { "type": "integer" }, "onboarding_url": { "type": "string" }, "expires_at": { "type": "string" }, "status": { "type": "string" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "createClientLoginLink", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "the client workspace_registration_id", "x-ms-summary": "ID" } ], "responses": { "201": { "description": "Login link", "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "login_url": { "type": "string" }, "expires_at": { "type": "string" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "pauseClientWorkspace", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "the client workspace_registration_id", "x-ms-summary": "ID" } ], "responses": { "200": { "description": "Paused", "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "status": { "type": "string" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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.", "operationId": "resumeClientWorkspace", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "the client workspace_registration_id", "x-ms-summary": "ID" } ], "responses": { "200": { "description": "Resumed", "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "status": { "type": "string" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "deleteClientWorkspace", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "description": "the client workspace_registration_id", "x-ms-summary": "ID" } ], "responses": { "200": { "description": "Deleted", "schema": { "type": "object", "properties": { "workspace_registration_id": { "type": "integer" }, "status": { "type": "string" } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } }, "/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. ...", "operationId": "mcpJsonRpc", "parameters": [ { "name": "body", "in": "body", "required": true, "x-ms-summary": "Request body", "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" ] } } ], "responses": { "200": { "description": "JSON-RPC result", "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string" }, "id": { "type": "integer" }, "result": { "type": "object", "properties": { "protocolVersion": { "type": "string" }, "serverInfo": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } } } } } } } }, "default": { "description": "Error", "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "object", "description": "field \u2192 problem map on validation_failed" }, "docs": { "type": "string", "description": "Optional. A link to the developer documentation for resolving this error, built from the requesting host so white-label developers get their own domain. Currently returned on 402 api_subscription_inactive." } } } } } } } } } } }