# Socialit Docs (full text) Omitted here (typed Focus mode aliases of the generic Focus operations; each is available as Markdown): https://socialit.com/docs/api-reference/focus-bluesky.md, https://socialit.com/docs/api-reference/focus-discord.md, https://socialit.com/docs/api-reference/focus-facebook-page.md, https://socialit.com/docs/api-reference/focus-google-business-profile.md, https://socialit.com/docs/api-reference/focus-instagram.md, https://socialit.com/docs/api-reference/focus-linkedin.md, https://socialit.com/docs/api-reference/focus-mastodon.md, https://socialit.com/docs/api-reference/focus-pinterest.md, https://socialit.com/docs/api-reference/focus-reddit.md, https://socialit.com/docs/api-reference/focus-snapchat.md, https://socialit.com/docs/api-reference/focus-threads.md, https://socialit.com/docs/api-reference/focus-tiktok.md, https://socialit.com/docs/api-reference/focus-x.md, https://socialit.com/docs/api-reference/focus-youtube.md # Ads > One ads API over Meta, Google, LinkedIn, TikTok, Pinterest, X, Reddit and ChatGPT ads, with campaigns, boosts, audiences, insights, lead gen, pixels and conversions. The Ads API is one platform-neutral model over **Meta (Facebook and Instagram), Google Ads, LinkedIn, TikTok, Pinterest, X, Reddit and OpenAI (ChatGPT) ads**. It has two reference groups: | Reference | MCP toolset | Covers | |---|---|---| | [Ads](/docs/api-reference/ads/) | `ads` | Connections, campaigns, ad sets, ads, boosts, creatives, targeting, audiences, insights, Google Ads specifics | | [Ads: accounts & measurement](/docs/api-reference/ads-accounts-measurement/) | `ads_measurement` | Ad accounts, users and finance, labels, tracking tags (pixels), lead forms and leads, product catalogs, conversions | Every operation needs the `ads` feature (Business and Enterprise). Money is a decimal number in the ad account's currency (`50` = 50.00 EUR), never micros or cents. ## 1. Connect an ads account `GET /v1/connect/{platform}/ads` (for example `meta_ads`, `google_ads`, `tiktok_ads`) returns the network's authorization URL, or connects immediately when an existing posting account's token can be reused. ChatGPT ads connect with an API key (`POST /v1/connect/openai-ads/credentials`). A connection (`adc_…`) discovers its **ad accounts** (`ada_…`). Socialit syncs them every 30 minutes and backfills 90 days on connect (`ad_account.initial_sync_completed`). Synced reads answer `202` with `backfill_pending: true` until the first backfill finishes. Live operations select the ad account with `ad_account_id`, or `connection_id` plus `platform_ad_account_id` (such as `act_123`). ## 2. Read campaigns and performance | Endpoint | Returns | |---|---| | `GET /v1/ads/campaigns`, `/v1/ads/ad-sets`, `/v1/ads` | Synced objects with rolled-up metrics (`live=true` reads through) | | `GET /v1/ads/tree` | Campaign → ad set → ad hierarchy | | `GET /v1/ads/timeline` | Daily metrics per ad account | | `GET /v1/ads/campaigns/{id}/analytics`, `/v1/ads/{id}/analytics` | Summary, daily series and breakdowns | | `GET /v1/ads/insights`, `POST /v1/ads/insights/reports` | Flexible live insights and async reports | ## 3. Create ads `POST /v1/ads` builds the whole tree (campaign → ad set → creative → ad) in one call, or attaches to an existing campaign or ad set. Objectives are portable (`traffic`, `engagement`, `awareness`, `video_views`, `lead_generation`, `conversions`, …) and mapped to each network. ```bash curl -X POST https://api.socialit.com/v1/ads/boost \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: boost-launch-post" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_5Rt8Yp1Xn3Vb8Kd5SzHc2Lm9Qw4", "post_id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd", "name": "Boost: Focus mode launch", "goal": "engagement", "budget": { "type": "daily", "amount": 20 }, "end_time": "2026-10-27T23:59:00Z" }' ``` - `POST /v1/ads/boost` promotes an organic post and keeps its engagement. - `POST /v1/ads/messaging` creates click-to-message ads (Messenger, Instagram Direct); `POST /v1/ads/call` creates click-to-call ads. - Pass `validate_only: true` (Meta, Google, OpenAI) to dry-run a create or update. - Pause or resume with `…/status`, bulk with `POST /v1/ads/campaigns/bulk-status`; duplicate campaigns, ad sets and ads where the network allows. - Creatives, images and videos have their own libraries (`/v1/ads/creatives`, `/v1/ads/images`, `/v1/ads/videos`); `POST /v1/ads/preview` renders previews before you spend. Not every network supports every operation. Unsupported calls answer `409 capability_not_supported` with `platform` and `capability`; missing permissions answer `409 missing_scopes` with a `reconnect_url`. ## Targeting and audiences Search any targeting dimension (`GET /v1/ads/targeting/search`), browse the category tree, and estimate reach (`POST /v1/ads/targeting/reach-estimate`). Custom audiences live at `/v1/ads/audiences`; `POST /v1/ads/audiences/{id}/users` adds people (plain emails and phones are SHA-256 hashed server-side). ## Google Ads specifics Keywords and negative keywords, Keyword Planner ideas and historical metrics, recommendations (apply or dismiss), portfolio bid strategies, shared budgets, campaign assets (sitelinks, callouts, snippets), Performance Max asset groups, search terms and Local Services leads. ## Measurement - **Tracking tags** (pixels): create, share and diagnose them per ad account. - **Lead gen:** lead forms (`/v1/ads/lead-forms`) and stored leads (`/v1/ads/leads`). Every new lead fires `lead.received`, from Meta webhooks, live reads or LinkedIn polling. - **Conversions:** send server-side events to the networks' Conversions APIs, manage conversion actions and check Event Match Quality. - **Catalogs:** Meta product catalogs with their products, feeds and product sets (`/v1/ads/catalogs`). ## Webhooks `ad.created`, `ad.updated`, `ad.status_changed`, `ad_campaign.*`, `ad_audience.*`, `ad_insights_report.completed`, `ad_connection.*`, `ad_account.*`, `lead.received` and `tracking_tag.*`. See [Ads events](/docs/api-reference/webhook-events/#events-ads). --- Source: https://socialit.com/docs/ads/ # Analytics > Post metrics, account analytics, platform-native insights, best time to post and inbox analytics, normalized across networks. Socialit stores daily snapshots of account and post metrics, so history survives even when a network only returns recent data. Everything is in the [Analytics](/docs/api-reference/analytics/) reference (MCP toolset `analytics`). ## Conventions - `from_date` and `to_date` are UTC days (`YYYY-MM-DD`, inclusive). - `account_id`, `profile_id` and `platform` filter every aggregate; you only see accounts you can access. - `source=all|socialit|external` separates posts published through Socialit from posts imported from the network. - Metrics are normalized: `impressions`, `reach`, `views`, `likes`, `comments`, `shares`, `saves`, `clicks`. A metric a network does not report is `null`, never `0`. - `engagement_rate` is a percentage: engagements ÷ (impressions, else reach, else views) × 100. ## Post analytics ```bash curl "https://api.socialit.com/v1/analytics?platform=instagram&from_date=2026-09-01&to_date=2026-09-30&sort=engagement_rate" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` | Endpoint | Returns | |---|---| | `GET /v1/analytics` | Paginated post analytics with an overview | | `GET /v1/analytics/posts/{postId}` | One post (`pst_…`, `sp_…` or a network post ID); `202` while a sync is pending | | `GET /v1/analytics/post-timeline?post_id=…` | Daily metric history of one post | | `GET /v1/analytics/delta?cursor=…` | Only what changed since your last cursor (sync into your warehouse) | | `POST /v1/posts/sync-external` | Import posts published natively on the network now | ## Aggregates `GET /v1/analytics/dashboard`, `/daily-metrics`, `/best-time`, `/content-decay` and `/posting-frequency` answer the usual questions: how are we doing, when should we post, how fast do posts fade and does posting more help. `GET /v1/accounts/follower-stats` returns follower counts and growth. ## Account and platform-native insights - `GET /v1/analytics/accounts/{accountId}` returns stored account analytics for any network, `…/demographics` the audience, and `…/reports/{report}` runs a network report live. - Native insights keep each network's own vocabulary: YouTube channel insights, daily views, retention and demographics; Instagram account insights, follower history and online followers; Facebook Page insights, post earnings and reactions; TikTok account insights; LinkedIn organization and personal stats; Google Business Profile performance and search keywords. - `POST /v1/analytics/accounts/{accountId}/sync` queues a refresh; `analytics.synced` fires when a sync cycle completes. Deeper, network-specific analytics (YouTube Analytics groups and reporting jobs, Reddit traffic, Pinterest audience insights…) are [Focus mode](/docs/focus-mode/) resources. ## Inbox analytics `GET /v1/analytics/inbox/volume`, `/heatmap`, `/source-breakdown`, `/response-time`, `/top-accounts` and `/conversations` measure the [inbox](/docs/inbox/): message volume, busy hours, response times and per-conversation stats. They need the `inbox` feature. ## History and network rules Your plan sets how far back you can read: 30 days on Free, 1 year on Pro, 2 years on Business, unlimited on Enterprise. An older `from_date` answers `403 analytics_history_limit`. Some networks restrict how their numbers may be combined. YouTube figures are never merged into cross-network totals: aggregates carry `calculated: true` and a `platform_breakdown`, and YouTube engagement rate is `null`. Pinterest analytics are fetched live and never stored, so stored aggregates exclude Pinterest. --- Source: https://socialit.com/docs/analytics/ # Errors > The single error format of the Socialit API, its error types and HTTP status codes, and how to handle network errors. Every error, from validation to a network refusing a post, uses one shape: ```json { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The post cannot be published to X.", "param": "content", "errors": { "content": ["Too long for X (280)"] }, "platform": "x", "platform_code": "186", "doc_url": "https://socialit.com/docs/networks/x/" }, "request_id": "req_4hQx…" } ``` | Field | Meaning | |---|---| | `type` | The category (table below). Branch on this first. | | `code` | A stable, specific code such as `validation_failed`, `invalid_api_key` or `plan_required`. | | `message` | A human-readable explanation. Don't parse it. | | `param` | The request field the error is about, when there is one. | | `errors` | Field-by-field messages for validation errors. | | `platform`, `platform_code` | The network and its own error code, when the network refused. | | `request_id` | Include it when you contact support. | ## Types | `type` | Status | When | |---|---|---| | `invalid_request_error` | 400, 422 | Malformed request or validation failed | | `authentication_error` | 401 | Missing, invalid or revoked credentials | | `permission_error` | 403 | The credential can't do this, or can't access this profile | | `not_found_error` | 404 | The object doesn't exist or isn't visible to you | | `conflict_error` | 409 | The request conflicts with the current state, or reused an idempotency key | | `plan_limit_error` | 402, 403 | Your plan doesn't include this, or a limit was reached; includes `usage` and `required_plan` | | `rate_limit_error` | 429 | Too many requests; see [Rate limits](/docs/api-reference/rate-limits/) | | `platform_error` | 502 | The network returned an error | | `api_error` | 500 | Something went wrong on our side | ## Handling them - `4xx` errors won't succeed if repeated unchanged. Fix the request first. - Retry `429`, `502` and `5xx` with exponential backoff, and use an [idempotency key](/docs/api-reference/idempotency/) so retries are safe. - `409 conflict_error` with code `account_needs_reconnect` means the account's token was revoked: reconnect it (the error and the `account.needs_reconnect` webhook carry the account). `403 missing_scopes` lists `missing_scopes` and a `reconnect_url` that upgrades them. - `403 plan_limit_error` with `plan_required` names the `required_plan`; `402 insufficient_credits` means prepaid X credits ran out. See [Billing and usage](/docs/billing-usage/#plan-errors). - Network-specific operations answer `409 capability_not_supported` (or `422 not_supported`) when a network can't do something, with `platform` and `capability`. --- Source: https://socialit.com/docs/api-reference/errors/ # Idempotency > Make create and send requests safe to retry with the Idempotency-Key header. Networks are slow and connections drop. To retry a request without publishing or sending twice, send an `Idempotency-Key` header with a unique value, such as a UUID or your own record ID: ```bash curl -X POST https://api.socialit.com/v1/posts \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: 6f1c2a8e-launch-2026-10-14" \ -H "Content-Type: application/json" \ -d '{ "content": "Hello", "account_ids": ["sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd"], "publish_now": true }' ``` - Every `POST` that creates, sends or runs an action accepts the header. Each endpoint in the [API reference](/docs/api-reference/) that honours it lists the `Idempotency-Key` header (and the OpenAPI document marks it with `x-idempotent: true`). - Keys are 1 to 255 characters of `A-Z a-z 0-9 _ - : .` and are scoped to the workspace and the operation. - Socialit stores the first successful (`2xx`) response for **24 hours**. Repeating the request with the same key and body returns it again with `Idempotent-Replayed: true`, without doing the work twice. - The same key with a different body answers `422 idempotency_key_reused`. A duplicate sent while the first is still running answers `409`. - Error responses are not stored: fix the request and retry with the same key. --- Source: https://socialit.com/docs/api-reference/idempotency/ # API reference > The Socialit REST API v1: base URL, authentication, conventions and every resource. The Socialit API is a REST API over HTTPS with JSON bodies. Every endpoint is generated from our OpenAPI 3.1 document, which you can download from `https://api.socialit.com/v1/openapi.json` to generate a client in any language. `GET https://api.socialit.com/v1` ## Conventions - **Authentication:** `Authorization: Bearer `. See [Authentication](/docs/authentication/). - **Objects:** flat JSON, snake_case fields, an `object` type and prefixed IDs. See [Objects and IDs](/docs/concepts/objects/). - **Creates** return `201` with the object; **updates** use `PATCH` and return `200` with the full object; **deletes** return `200` with `{ "object", "id", "deleted": true }`; **actions** are `POST /resource/{id}/{verb}`. - **Lists** share one envelope, filters and sorting. See [Pagination and filtering](/docs/api-reference/pagination/). - **Errors** share one shape everywhere. See [Errors](/docs/api-reference/errors/). - **Retries:** send an `Idempotency-Key` on creates. See [Idempotency](/docs/api-reference/idempotency/). - **Limits:** per workspace, with `RateLimit-*` headers. See [Rate limits](/docs/api-reference/rate-limits/). ## Resources Resources are grouped like the sidebar. Each page lists its endpoints with parameters, request and response schemas, examples and code samples in cURL, Node.js, Python, PHP and Go, plus the MCP tool call. Every operation is also an [MCP tool](/docs/mcp/) named after its operation ID in kebab-case (`createPost` → `create-post`), shown on each endpoint. The [OpenAPI document](https://api.socialit.com/v1/openapi.json) carries the same metadata as vendor extensions: `x-tagGroups`, and per operation `x-access` (scope), `x-mcp-tool`, `x-toolset`, `x-idempotent` and `x-zernio` (the [Zernio operations](/docs/migrating-from-zernio/) it replaces). ## Resources ### Core - [Accounts](/docs/api-reference/accounts/) (44): Profiles, account groups, connected social accounts and connect flows. - [API Keys](/docs/api-reference/api-keys/) (7): Workspace API keys. Keys are stored hashed; the secret is shown once. - [Webhooks](/docs/api-reference/webhooks/) (12): Signed HTTPS callbacks for workspace events. Each delivery carries X-Socialit-Signature (hex HMAC-SHA256 of ${timestamp}.${body} with the webhook secret) and X-Socialit-Timestamp. Failed deliveries retry after 5m, 30m, 2h, 5h, then every 12h (11 attempts); a webhook failing for 3 days is disabled. - [Events](/docs/api-reference/events/) (3): The workspace event log (the payloads webhooks receive) and the event type catalog. - [Logs](/docs/api-reference/logs/) (3): API request logs (public API + MCP) and the workspace activity log. - [Invitations](/docs/api-reference/invitations/) (1): Email invitations, invite codes and invite links. - [Users](/docs/api-reference/users/) (2): People with access to the workspace. ### Publishing - [Posts](/docs/api-reference/posts/) (24): Create, schedule and publish posts to connected accounts; track per-account results. - [Queues](/docs/api-reference/queues/) (7): Recurring posting schedules. Posts created with queue: true take the next free slot. - [Media](/docs/api-reference/media/) (10): Upload images, videos and documents for posts (and inbox attachments). - [Templates](/docs/api-reference/templates/) (5): Reusable post content with media and network options. - [Tools](/docs/api-reference/tools/) (7): Validate posts and media before publishing; feedback and changelog. ### Inbox - [Inbox](/docs/api-reference/inbox/) (72): Unified inbox: direct messages, comments, reviews and mentions across networks, plus messaging settings, X engagement and Reddit discovery. ### Analytics - [Analytics](/docs/api-reference/analytics/) (40): Post and account analytics, platform-native insights and inbox analytics. Dates are UTC days (YYYY-MM-DD). History is limited by the plan (free 30 d, pro 365 d, business 730 d). ### Automation & CRM - [Contacts](/docs/api-reference/contacts/) (16): CRM contacts: one person across platforms, linked to channels (per-account platform identities such as an Instagram or Messenger user ID). Contacts are created automatically from inbound messages; tags and custom fields feed broadcasts, sequences and workflows. - [Custom Fields](/docs/api-reference/custom-fields/) (5): Contact custom field definitions (text, number, date, boolean, select). Slugs are unique per workspace. - [Broadcasts](/docs/api-reference/broadcasts/) (11): Bulk sends to contacts on one account (Messenger / Instagram within the 24 h window or with HUMAN_AGENT, X, Bluesky…), rate limited per channel with per-recipient delivery status. Each recipient is one message. - [Sequences](/docs/api-reference/sequences/) (10): Time-based drips: ordered steps (delay, message, optional condition) sent to enrolled contacts on one account; contacts exit on reply or unsubscribe. - [Workflows](/docs/api-reference/workflows/) (18): Event-driven automation graphs: a trigger (message, keyword, comment, referral, reaction, contact change, API call, schedule) and nodes (send message, reply / private reply, wait, condition, HTTP request, AI reply with Claude, tags, fields, sequences, assignment). Every graph change records a version; runs are durable and have a timeline. - [Comment Automations](/docs/api-reference/comment-automations/) (6): Comment-to-DM (ManyChat-style): keyword rules per account or post answer comments with a private DM (Instagram, Facebook) and / or a public reply (also TikTok, Threads, LinkedIn, YouTube, Bluesky, Reddit), with audience filters, follow gates, repeat policies and tracked links. Each comment is answered at most once. ### Ads - [Ads](/docs/api-reference/ads/) (123): Unified ads across Meta, Google, LinkedIn, TikTok, Pinterest, X, Reddit and OpenAI (ChatGPT) Ads: connections, campaigns, ad sets, ads, creatives, insights, targeting, audiences, Google Ads specifics, Ad Library, Reach & Frequency. - [Ads: accounts & measurement](/docs/api-reference/ads-accounts-measurement/) (135): Ad accounts, account-level ad management, tracking tags, lead gen, product catalogs and conversions. ### Platform tools - [Platform tools](/docs/api-reference/platform-tools/) (91): Network-specific tools on a connected account: Google Business Profile listing, reviews, media and verification; Facebook Pages; LinkedIn organizations and mentions; Instagram stories, audio and discovery; Pinterest boards; YouTube playlists and transcripts; Reddit subreddits, flairs and votes; TikTok creator info; Discord server management; Bluesky settings. ### Focus mode - [Focus](/docs/api-reference/focus/) (10): Focus mode: everything a network's API allows for one connected account. The manifest lists the resources (with JSON schemas for tables and forms); the generic operations run them. Typed per-network aliases live under the "Focus · " tags. - [Focus · Bluesky](/docs/api-reference/focus-bluesky/) (168): Typed Focus mode operations for Bluesky accounts, generated from the Bluesky focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · Discord](/docs/api-reference/focus-discord/) (145): Typed Focus mode operations for Discord accounts, generated from the Discord focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · Facebook Page](/docs/api-reference/focus-facebook-page/) (158): Typed Focus mode operations for Facebook Page accounts, generated from the Facebook Page focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · Google Business Profile](/docs/api-reference/focus-google-business-profile/) (89): Typed Focus mode operations for Google Business Profile accounts, generated from the Google Business Profile focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · Instagram](/docs/api-reference/focus-instagram/) (103): Typed Focus mode operations for Instagram accounts, generated from the Instagram focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · LinkedIn](/docs/api-reference/focus-linkedin/) (64): Typed Focus mode operations for LinkedIn accounts, generated from the LinkedIn focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · Mastodon](/docs/api-reference/focus-mastodon/) (337): Typed Focus mode operations for Mastodon accounts, generated from the Mastodon focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · Pinterest](/docs/api-reference/focus-pinterest/) (64): Typed Focus mode operations for Pinterest accounts, generated from the Pinterest focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · Reddit](/docs/api-reference/focus-reddit/) (292): Typed Focus mode operations for Reddit accounts, generated from the Reddit focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · Snapchat](/docs/api-reference/focus-snapchat/) (56): Typed Focus mode operations for Snapchat accounts, generated from the Snapchat focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · Threads](/docs/api-reference/focus-threads/) (57): Typed Focus mode operations for Threads accounts, generated from the Threads focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · TikTok](/docs/api-reference/focus-tiktok/) (65): Typed Focus mode operations for TikTok accounts, generated from the TikTok focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · X](/docs/api-reference/focus-x/) (177): Typed Focus mode operations for X accounts, generated from the X focus module (same behaviour as the generic /accounts/{accountId}/focus routes). - [Focus · YouTube](/docs/api-reference/focus-youtube/) (170): Typed Focus mode operations for YouTube accounts, generated from the YouTube focus module (same behaviour as the generic /accounts/{accountId}/focus routes). ### Account & billing - [Billing](/docs/api-reference/billing/) (9): Plans, subscriptions, payment methods, invoices, usage and prepaid credits. - [Connected Apps](/docs/api-reference/connected-apps/) (2): Third-party apps and AI agents connected with OAuth. - [Support Assistant](/docs/api-reference/support-assistant/) (3): Ask Socialit support questions (failed posts, account connection, API usage). Answers are generated with Claude, grounded on the Socialit documentation and on the context you pass (post, account, failed request). Runs are asynchronous: poll the run or listen to support_run.completed. --- Source: https://socialit.com/docs/api-reference/ # Pagination and filtering > The list envelope, page-based pagination, filters with field.condition=value, and sorting. Every list endpoint takes `page` (from 1) and `limit` (default 20, max 100) and returns the same envelope: ```json { "object": "list", "data": [{ "object": "post", "id": "pst_…" }], "page": 1, "limit": 20, "total": 123, "has_more": true, "next_page_url": "https://api.socialit.com/v1/posts?page=2&limit=20", "previous_page_url": null } ``` `total` can be `null` on very large lists. Follow `next_page_url` until `has_more` is `false`. ## Filters Filter with `field.condition=value` query parameters. Each list documents which fields it accepts. | Type | Conditions | |---|---| | Strings | `exact`, `not_exact`, `contains`, `not_contains`, `starts_with`, `ends_with`, `empty`, `not_empty` | | Numbers | `gt`, `gte`, `lt`, `lte` | | Dates | `before`, `after` | ```bash curl "https://api.socialit.com/v1/posts?content.contains=launch&scheduled_at.after=2026-10-01T00:00:00Z" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Filters combine with AND. Add `match=or` to match any of them. Common filters also have plain shortcuts, such as `?status=scheduled&profile_id=pro_…&platform=instagram`. ## Sorting `sort=&order=asc|desc`, for example `?sort=scheduled_at&order=asc`. ## Cursor lists Lists read live from a network (Focus mode resources, ad libraries, catalog products) can't jump to a page. They use the same envelope plus a cursor: ```json { "object": "list", "data": [{ "id": "dQw4w9WgXcQ", "title": "Launch video" }], "limit": 25, "total": null, "has_more": true, "next_cursor": "CBkQAA", "next_page_url": "https://api.socialit.com/v1/accounts/sa_…/focus/videos?limit=25&cursor=CBkQAA", "previous_page_url": null } ``` Pass `next_cursor` back as `cursor` (some endpoints also accept `after`), or follow `next_page_url`, until `has_more` is `false`. `total` is set only when the network reports it. ## MCP List tools take the same parameters, plus `filters: [{ "field": "status", "condition": "exact", "value": "scheduled" }]`, which maps to `status.exact=scheduled`. --- Source: https://socialit.com/docs/api-reference/pagination/ # Rate limits > Request budgets per workspace and plan, per-operation limits, the RateLimit headers, network limits and how to handle 429 responses. The public API and the MCP server share one hourly request budget per workspace. All of a workspace's API keys and OAuth connections count against it. | Plan | Requests per hour | |---|---| | Free | 600 | | Pro | 6,000 | | Business | 30,000 | | Enterprise | 120,000 or more | Every response carries the current state: - `RateLimit-Limit`: the budget for the window. - `RateLimit-Remaining`: requests left in the window. - `RateLimit-Reset`: seconds until the window resets. When the budget is spent, the API answers `429` with `rate_limit_error` and a `Retry-After` header (seconds). Wait that long, then retry; back off exponentially if it happens again. `GET /v1/usage` shows the current window. ## Other limits | Limit | Error | |---|---| | Some operations have their own, tighter bucket (for example re-verification codes, test sends) | `429 rate_limit_error` with `Retry-After` | | Posts per account per day (plan) | `429 posts_per_day_limit` with `usage` | | A network's own limit (posts per day on TikTok or Instagram, YouTube quota units, Reddit QPM) | `429 platform_rate_limited` with `Retry-After`, or a `platform_error` | | Messaging pace of broadcasts per channel | Paced automatically, see [Broadcasts](/docs/crm-automations/#broadcasts) | > **Tip:** Use [webhooks](/docs/webhooks/) and `GET /v1/analytics/delta` instead of polling, and [idempotency keys](/docs/api-reference/idempotency/) so retries after a 429 are safe. --- Source: https://socialit.com/docs/api-reference/rate-limits/ # Webhook events > Every webhook event type Socialit emits, by area, with the shape of its data payload. This page is generated from the event catalog the API uses (`packages/core/src/events.js`), so it always matches what `GET /v1/events/names` returns and what webhooks can subscribe to. Every delivery wraps the event's `data` in the same envelope; see [Webhooks](/docs/webhooks/) for signatures and retries. - Subscribe with `events: ["post.published", …]` on [`POST /v1/webhooks`](/docs/api-reference/webhooks/#create-webhook), or `all_events: true` for everything (including types added later). - Payloads embed full objects in their API shape (a `post`, a `message`, an `account` reference) unless noted. - Types are `.` and never renamed; new ones are added as features land. ## Envelope ```json { "id": "evt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "object": "event", "type": "post.published", "created_at": "2026-10-13T09:00:04.512Z", "workspace_id": "ws_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "test": false, "data": { "post": { "object": "post", "id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd", "status": "published" } } } ``` ## Posts | Event | Description | Payload (`data`) | |---|---|---| | `post.scheduled` | A post was scheduled for publishing. | | | `post.publishing` | A post started publishing to its accounts. | | | `post.published` | A post was published to every target account. | | | `post.partially_published` | A post was published to some target accounts and failed on others. | | | `post.failed` | A post failed to publish on every target account. | | | `post.deleted` | A post was deleted from Socialit. | | | `post.unpublished` | A published post was removed from the network. data: { post, posting }. | | | `post.cancelled` | A scheduled or publishing post was cancelled, or every published target was unpublished. | | | `post.edited` | A published post was edited on the network. data: { post, posting }. | | | `post.recycled` | An evergreen post was cloned and rescheduled. data: { post (the clone), source_post_id }. | | | `post.approval_requested` | A post is waiting for approval. data: { post, approval }. | | | `post.approved` | A pending post was approved. data: { post, approval, comment }. | | | `post.rejected` | A pending post was rejected and moved back to draft. data: { post, approval, comment }. | | | `posting.published` | One target account finished publishing (before the post roll-up). data: { post, posting }. | | | `posting.failed` | One target account failed permanently (retryable failures stay quiet). data: { post, posting }. | | ## Accounts | Event | Description | Payload (`data`) | |---|---|---| | `account.connected` | A social account was connected or reconnected. Payload: { account, reconnected, connect_flow }. | | | `account.disconnected` | A social account was disconnected. Payload: { account, disconnection_type: intentional\|unintentional, reason }. | | | `account.needs_reconnect` | A social account lost its authorization and must be reconnected. Payload: { account, reason, platform_code }. | | | `account.updated` | A social account label, defaults or profile assignment changed. Payload: { account, changes }. | | ## Inbox | Event | Description | Payload (`data`) | |---|---|---| | `message.received` | A direct message was received. | Payloads: { message, conversation, account } (message.failed adds error). | | `message.sent` | A direct message was sent (from Socialit, or echoed from the network app). | Payloads: { message, conversation, account } (message.failed adds error). | | `message.delivered` | A sent direct message was delivered. | Payloads: { message, conversation, account } (message.failed adds error). | | `message.read` | A sent direct message was read by the recipient. | Payloads: { message, conversation, account } (message.failed adds error). | | `message.failed` | A sent direct message failed to deliver. | Payloads: { message, conversation, account } (message.failed adds error). | | `message.edited` | A direct message was edited (payload carries the edit history). | Payloads: { message, conversation, account } (message.failed adds error). | | `message.deleted` | A direct message was deleted or unsent. | Payloads: { message, conversation, account } (message.failed adds error). | | `reaction.received` | A participant added or removed a reaction on a message. | { reaction: { emoji, action: added\|removed, message_id, sender, reacted_at }, message, conversation, account } | | `conversation.created` | A new conversation started. | { conversation, account }, conversation.updated adds changes[]. | | `conversation.updated` | A conversation changed (status, assignment, read state). | { conversation, account }, conversation.updated adds changes[]. | | `conversation.control_changed` | Conversation handover: the app answering a conversation changed. | { conversation, account, control: { owner, previous_owner, owner_app_id } } | | `comment.received` | A comment was received on a post. | { comment, post, account } | | `comment.replied` | A reply was posted to a comment. | { comment, post, account } | | `comment.hidden` | A comment was hidden. | { comment, post, account } | | `comment.unhidden` | A hidden comment was made visible again. | { comment, post, account } | | `comment.deleted` | A comment was deleted. | { comment, post, account } | | `review.received` | A review was received. | { review, account } | | `review.updated` | A reviewer edited their review text or rating. | { review, account } | | `review.replied` | A reply was posted to a review. | { review, account } | | `mention.received` | The account was mentioned. | { mention, account } | ## Contacts | Event | Description | Payload (`data`) | |---|---|---| | `contact.created` | A contact was created. | | | `contact.updated` | A contact was updated. | | | `contact.deleted` | A contact was deleted. | | | `contact.tag_added` | A tag was added to a contact (API, workflow add_tag node or comment-automation link click). Fires once per tag actually added; data: contact {id}, tag, source. | | | `contact.tag_removed` | A tag was removed from a contact. Fires once per tag actually removed; data: contact {id}, tag, source. | | | `contact.field_changed` | A contact custom field value changed (not on create); data: contact {id}, field, previous_value, value, source. | | ## Messaging | Event | Description | Payload (`data`) | |---|---|---| | `broadcast.scheduled` | A broadcast was scheduled. | | | `broadcast.sent` | A broadcast finished sending. | | | `broadcast.failed` | A broadcast failed. | | | `broadcast.sending` | A broadcast started sending to its recipients. | | | `broadcast.cancelled` | A scheduled or sending broadcast was cancelled. | | | `sequence.enrolled` | A contact was enrolled in a sequence. | | | `sequence.step_sent` | A sequence step was sent to a contact. | | | `sequence.completed` | A contact completed a sequence. | | | `sequence.exited` | A contact left a sequence, finished or not; exit_reason says why (completed, replied, manual, failed, unsubscribed, sequence_deleted). | | | `workflow.triggered` | A workflow run started (Zernio workflow.run.started). | | | `workflow.completed` | A workflow run ended; execution.status is completed, or exited for a run ended on purpose (Zernio workflow.run.completed). | | | `workflow.failed` | A workflow run failed; error says which node failed and why (Zernio workflow.run.failed). | | ## Ads | Event | Description | Payload (`data`) | |---|---|---| | `ad.created` | An ad was created through Socialit (create, boost, messaging / call ad, duplicate). data: { ad, campaign, ad_set }. | | | `ad.updated` | An ad was updated through Socialit. data: { ad, changes }. | | | `ad.deleted` | An ad was deleted or archived through Socialit. data: { ad }. | | | `ad.status_changed` | A campaign, ad set or ad changed effective status (sync, Meta webhook or a status write). data: { level, object, previous_status, status, platform_status, error, connection, ad_account } (Zernio ad.status_changed). | | | `ad.video.processed` | An async ad video finished processing (ready or error). data: { video, connection, ad_account } (Zernio ad.video.processed). | | | `ad_campaign.created` | An ad campaign was created through Socialit. data: { campaign }. | | | `ad_campaign.updated` | An ad campaign was updated through Socialit (name, budget, bidding, schedule). data: { campaign, changes }. | | | `ad_campaign.deleted` | An ad campaign was deleted or archived through Socialit. data: { campaign }. | | | `ad_audience.created` | A custom ad audience was created. data: { audience }. | | | `ad_audience.deleted` | A custom ad audience was deleted. data: { audience }. | | | `ad_insights_report.completed` | An async ads insights report finished (completed or failed). data: { report }. | | | `ad_connection.connected` | An ads connection was created or reconnected. data: { connection, ad_accounts, reconnected }. | | | `ad_connection.disconnected` | An ads connection was disconnected. data: { connection, reason }. | | | `ad_connection.needs_reconnect` | An ads connection lost its authorization. data: { connection, reason, platform_code }. | | | `ad_account.initial_sync_completed` | The first sync and 90-day backfill of an ads connection finished. data: { connection, ad_accounts, sync } (Zernio account.ads.initial_sync_completed). | | | `ad_account.sync_failed` | An ad account has not synced for 24 hours. data: { connection, ad_account, sync } (Zernio account.ads.sync_failed). | | | `ad_account.sync_recovered` | A failing ad account synced again. data: { connection, ad_account, sync } (Zernio account.ads.sync_recovered). | | | `lead.received` | A lead-gen form submission was stored (Meta leadgen webhook, a live form read, LinkedIn polling; test leads included). data: { lead, form: { id, name }, ad_account } (Zernio lead.received). | | | `ad_account.created` | An ad account was created (POST /ads/accounts) or found by a re-discovery. data: { ad_account, connection }. | | | `ad_account.updated` | An ad account changed (selection, profile, network settings, or name / status / currency on re-discovery). data: { ad_account, changes }. | | ## Analytics | Event | Description | Payload (`data`) | |---|---|---| | `analytics.synced` | An account's analytics sync cycle completed (poll-driven, roughly hourly). A trigger to pull: the payload carries no metrics, only { account, sync: { synced_at, posts_updated } }. | | ## Support assistant | Event | Description | Payload (`data`) | |---|---|---| | `support_run.completed` | The support assistant finished a question; run.status is completed, or needs_human when it handed the question to a person. Unscoped (profile-filtered webhooks never receive it). | | | `support_run.failed` | A support assistant question failed or expired. Unscoped. | | ## Workspace | Event | Description | Payload (`data`) | |---|---|---| | `member.joined` | A user joined the workspace. | | | `member.removed` | A user was removed from the workspace. | | | `webhook.test` | A test event sent from the dashboard or API. | | ## Billing | Event | Description | Payload (`data`) | |---|---|---| | `billing.subscription_created` | A plan subscription started (Stripe Checkout completed). | data: { subscription } (docs/api/groups/billing.md) | | `billing.subscription_updated` | The plan, billing interval, extra accounts, status or scheduled cancellation changed. | data: { subscription, previous: { plan, interval, extra_accounts, status, cancel_at_period_end } } | | `billing.subscription_canceled` | The plan subscription ended; the workspace is back on Free. | data: { subscription } | | `billing.invoice_paid` | An invoice was paid. | data: { invoice } | | `billing.payment_failed` | An invoice payment failed; update the payment method to keep the plan. | data: { invoice } | | `billing.credits_purchased` | Prepaid credits (X API pass-through) were added. | data: { credits: { amount_cents, balance_cents, pack_id, source } } | | `billing.accounts_over_limit` | Connected accounts exceed the plan allowance; publishing is paused for the accounts beyond it. | data: { accounts: { used, limit, paused_account_ids } } | --- Source: https://socialit.com/docs/api-reference/webhook-events/ # Authentication > Authenticate API requests with a workspace API key or an OAuth access token, and limit what each credential can do. Every request to `https://api.socialit.com/v1` carries a bearer token in the `Authorization` header. The token is either a **workspace API key** or an **OAuth access token**. ```bash curl https://api.socialit.com/v1/accounts \ -H "Authorization: Bearer sk_live_…" ``` ## API keys API keys belong to a workspace. Create them in **Manage → API keys** (workspace admins only). - Keys start with `sk_live_`. The full key is shown **once**, at creation. Socialit stores only a hash and a short display prefix. - **Permission:** `full` (read and write) or `read` (read only). - **Profiles:** optionally restrict a key to some profiles. The key then sees and acts on those profiles' accounts only, which is the safest way to give a key to one client or one integration. - **Expiry and rotation:** set an expiry date, regenerate a key, or delete it at any time. Treat keys like passwords: never commit them, never use them in browser code, and rotate them when someone leaves. ## OAuth 2.1 Apps and AI agents that act for *other* Socialit users use OAuth 2.1 with PKCE. Users approve the app on a consent screen and choose which workspaces it can reach. Scopes: | Scope | Allows | |---|---| | `read` | Read posts, accounts, inbox, analytics | | `write` | Create and change posts, reply in the inbox, upload media | | `admin` | Workspace administration: members, API keys, webhooks | | `offline_access` | A refresh token to keep access without the user present | Socialit supports dynamic client registration, so MCP clients such as Claude and Cursor register themselves; see [MCP server](/docs/mcp/). Users can review and revoke connected apps in **Account → Connected apps**. ## Verify a credential `GET /v1/auth/verify` returns the workspace, permission and type of the credential you sent, which is useful to check a key at startup: ```json { "object": "credential", "workspace": { "id": "ws_…", "name": "Northwind" }, "permission": "full", "type": "api_key", "scopes": [] } ``` ## Errors Missing, invalid, expired or revoked credentials return `401` with `authentication_error`. A valid credential without the right permission (a read-only key creating a post, a member without access to a profile) returns `403` with `permission_error`. See [Errors](/docs/api-reference/errors/). --- Source: https://socialit.com/docs/authentication/ # Billing and usage > Plans, the connected-account allowance, usage, X API pass-through credits, invoices and billing webhooks. Billing is mostly managed in the app (**Manage → Billing**). The API exposes everything you need to read state and react to it, in the [Billing](/docs/api-reference/billing/) reference (MCP toolset `billing`). Reads need the `owner`, `admin` or `billing` role, or any API key with `read`. Checkout, plan changes, payment methods and the customer portal are dashboard-only. ## Plans | Plan | Price | Accounts included | Extra account | API requests per hour | |---|---|---|---|---| | Free | $0 | 3 | – | 600 | | Pro | $25/mo ($20/mo yearly) | 25 | $2/mo | 6,000 | | Business | $250/mo ($200/mo yearly) | 250 | $1/mo | 30,000 | | Enterprise | Custom | Unlimited | Custom | 120,000+ | Posts are unlimited on every plan. Features such as broadcasts, automations, ads and hosted connect are plan-gated. `GET /v1/billing/plans` returns every plan with its features and limits. ## Allowance and usage ```bash curl https://api.socialit.com/v1/usage -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` `GET /v1/usage` returns connected accounts against the allowance, the current API request window, media storage and other metered limits. The **account allowance** is the plan's included accounts plus purchased extra accounts (plus lifetime seats on legacy deals). When a workspace ends up over its allowance (after a downgrade or cancellation), accounts stay connected but publishing pauses on the newest accounts beyond it, and `billing.accounts_over_limit` fires. `GET /v1/billing` returns `publishing_paused` and a `banner` you can show. ## Plan errors | Error | When | |---|---| | `403 plan_limit_error` / `plan_required` | The operation needs a feature your plan doesn't have (`required_plan` says which) | | `403 plan_limit_error` / `account_limit_reached` | Connecting would exceed the allowance (`usage: { used, limit, requested }`) | | `402 plan_limit_error` / `insufficient_credits` | X API calls without prepaid credits | | `403 plan_limit_error` / `analytics_history_limit` | Analytics older than your plan's history window | ## X API credits X charges per API call. Socialit passes that cost through from prepaid credits: `GET /v1/billing/x-pricing` shows the price table, `GET /v1/billing/credits` the balance and packs, and `GET /v1/usage/x-api` the usage per day, account and endpoint. Postings record `credits_charged`. ## Invoices and previews `GET /v1/billing/invoices` (filter by `status`) and `…/{id}` return invoices. `GET /v1/billing/preview?plan=business&interval=year&extra_accounts=10` previews a plan change with proration before you make it in the app. ## Webhooks `billing.subscription_created`, `billing.subscription_updated`, `billing.subscription_canceled`, `billing.invoice_paid`, `billing.payment_failed`, `billing.credits_purchased` and `billing.accounts_over_limit`. See [Billing events](/docs/api-reference/webhook-events/#events-billing). --- Source: https://socialit.com/docs/billing-usage/ # Objects and IDs > How Socialit objects, IDs, dates and the workspace hierarchy fit together. ## The hierarchy - A **workspace** holds members, billing, API keys and webhooks. - **Profiles** group accounts by brand or client. Members and API keys can be limited to some profiles. - **Accounts** are connected identities on a network. - **Posts** target one or more accounts; each target is a **posting** with its own status, network ID and URL. - **Conversations**, **messages**, **comments** and **reviews** make up the inbox; senders become **contacts**. ## IDs Every object has an ID made of a prefix and 27 base62 characters, such as `pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd`. The prefix tells you the type: | Prefix | Object | |---|---| | `ws_` | Workspace | | `pro_` | Profile | | `sa_` | Account | | `pst_` | Post | | `sp_` | Posting | | `med_` | Media | | `que_` | Queue | | `conv_` | Conversation | | `msg_` | Message | | `cmt_` | Comment | | `rev_` | Review | | `con_` | Contact | | `wh_` | Webhook | | `key_` | API key | References to other objects use `_id` and hold the ID, for example `profile_id`. ## Object shape Objects are flat JSON with snake_case fields, an `object` type and timestamps: ```json { "object": "account", "id": "sa_7Yt2pQ9xLmB4cRzV1nYt8aHsJw", "platform": "youtube", "name": "Northwind Studio", "status": "active", "created_at": "2026-10-01T08:12:44.381Z", "updated_at": "2026-10-13T16:42:07.118Z" } ``` Dates are ISO 8601 in UTC with milliseconds. Platform keys are `facebook`, `instagram`, `x`, `linkedin`, `threads`, `bluesky`, `pinterest`, `tiktok`, `youtube`, `google_business`, `reddit`, `snapchat`, `discord` and `mastodon`. The API also accepts `twitter` for `x` and `googlebusiness` for `google_business`. --- Source: https://socialit.com/docs/concepts/objects/ # Connecting accounts > Connect social accounts with OAuth from your app, hand your customers a white-label hosted connect link, or run the whole flow headless through the Connect API. A connected **account** (`sa_…`) is one identity on one network: an Instagram account, a Facebook Page, a YouTube channel, a Google Business location, a Discord channel. Accounts belong to **profiles** (`pro_…`), which group them by brand or client and scope who can see them. **Account groups** (`grp_…`) are free-form sets of accounts you can target in one post. Everything here is in the [Accounts](/docs/api-reference/accounts/) reference (MCP toolset `accounts`). Each connected account counts against your plan's account allowance; reconnects never do. ## Pick a method | Method | Best for | Endpoints | |---|---|---| | **OAuth redirect** | Your app sends the user to the network and gets them back | `GET /v1/connect/{platform}` | | **Hosted connect link** | Your customers connect on a branded Socialit page | `POST /v1/connect/links` | | **Headless** | You render every screen, including asset pickers | `GET /v1/connect/{platform}?headless=true`, `/v1/connect/select` | | **Credentials** | Networks without OAuth (Bluesky app passwords, Mastodon tokens) | `POST /v1/connect/{platform}/credentials` | `GET /v1/connect/platforms` lists every network with its connect methods. ## OAuth redirect 1. **Get an authorization URL.** `GET /v1/connect/linkedin?profile_id=pro_…&redirect_url=https://your-app.com/connected` returns `{ "object": "connect_url", "url", "state", "expires_at" }`. 2. **Send the user to `url`.** The network redirects to Socialit, which exchanges the code. 3. **The user lands on your `redirect_url`** with `?connected=linkedin&account_ids=sa_…&profile_id=pro_…`, or with `?error=&error_message=…` (`oauth_denied`, `invalid_state`, `no_targets`, `account_limit_reached`, …). Useful query parameters: | Parameter | Use | |---|---| | `profile_id` | Profile for the new accounts (default: the workspace default profile) | | `scope_set` | `core` (default) or `focus`: request the extra scopes [Focus mode](/docs/focus-mode/) needs | | `reconnect_account_id` | Refresh one account in place (keeps its profile, never counts against the allowance) | | `instance` | Mastodon server, such as `mastodon.social` (required for Mastodon) | | `login_method` | Instagram: `instagram_login` or `facebook_login` | When a login has several assets (Facebook Pages, LinkedIn organizations, Google Business locations, Pinterest boards, YouTube channels…), Socialit shows its own picker before redirecting back. ## Hosted connect links (white label) Send your customer one link. They see your name, logo and colors, pick networks, sign in and choose assets; the accounts land in the profile you chose. Requires the `hostedConnect` feature (Business and Enterprise). ```bash curl -X POST https://api.socialit.com/v1/connect/links \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "pro_8Lq2Vx7Bn4Mc1Zr8Tw3Ys6Hd0Kp", "name": "Acme onboarding", "platforms": ["instagram", "facebook", "linkedin", "tiktok"], "branding": { "name": "Acme Agency", "logo_url": "https://acme.example/logo.png", "primary_color": "#1D4ED8" }, "redirect_url": "https://your-app.com/settings/social", "expires_in": 604800, "max_uses": 1 }' ``` The response has the link `url` (`https://api.socialit.com/hosted/connect/`). At the end the browser goes to `redirect_url?account_ids=sa_1,sa_2&platform=…&profile_id=…`, or to a branded success page. List, inspect and revoke links with `GET /v1/connect/links` and `DELETE /v1/connect/links/{id}`. Listen for `account.connected` to know when accounts arrive. ## Headless For a fully custom UI, add `headless=true`. Multi-asset networks then return to your `redirect_url` with `?pending_token=…&step=select_page&platform=facebook` instead of showing the Socialit picker: 1. `GET /v1/connect/pending-data?token=…` returns the targets the user can pick (Pages, organizations, locations, boards…). 2. Render your picker. 3. `POST /v1/connect/select` with `{ "token": "…", "target_ids": ["…"] }` connects them and returns the accounts. Network-specific pickers with Zernio-compatible bodies also exist (`/v1/connect/facebook/select-page`, `/v1/connect/linkedin/select-organization`, `/v1/connect/googlebusiness/select-location`, …). Pending selections expire after 30 minutes. If your app receives the OAuth `code` itself, complete the flow with `POST /v1/connect/{platform}` and `{ code, state }`. ### Networks without OAuth | Network | How | |---|---| | Bluesky | `POST /v1/connect/bluesky/credentials` with the handle and an **app password** (or OAuth with `identifier`) | | Discord | `POST /v1/connect/discord` with `guild_id` and `channel_ids` once the bot is in the server | ## Health, scopes and reconnecting Socialit refreshes tokens in the background. `GET /v1/accounts/health` (or `/v1/accounts/{id}/health`) reports token state, granted scopes and what each account can do. An account whose access was revoked becomes `needs_reconnect` and emits `account.needs_reconnect`; send the user through `GET /v1/connect/{platform}?reconnect_account_id=sa_…` to fix it. `PATCH /v1/accounts/{id}` renames an account or moves it to another profile. `DELETE /v1/accounts/{id}` disconnects it (`account.disconnected`). --- Source: https://socialit.com/docs/connecting-accounts/ # CRM and automations > Contacts and custom fields across networks, broadcasts, drip sequences, event-driven workflows and comment-to-DM automations. Everyone who writes to one of your accounts becomes a **contact**. Contacts feed **broadcasts** (one-off bulk sends), **sequences** (time-based drips), **workflows** (event-driven graphs) and **comment automations** (comment-to-DM). Everything belongs to a profile and is scoped like the rest of the API. | Resource | Reference | MCP toolset | Plan | |---|---|---|---| | Contacts, tags, channels | [Contacts](/docs/api-reference/contacts/) | `contacts` | Every plan | | Custom fields | [Custom Fields](/docs/api-reference/custom-fields/) | `custom_fields` | Every plan | | Broadcasts | [Broadcasts](/docs/api-reference/broadcasts/) | `broadcasts` | `broadcasts` feature (Pro) | | Sequences | [Sequences](/docs/api-reference/sequences/) | `sequences` | `automations` feature (Pro) | | Workflows | [Workflows](/docs/api-reference/workflows/) | `workflows` | `automations` feature (Pro) | | Comment automations | [Comment Automations](/docs/api-reference/comment-automations/) | `comment_automations` | `automations` feature (Pro) | Channels can be `instagram`, `facebook`, `x`, `bluesky`, `reddit`, `discord`, `mastodon` and `tiktok`. ## Contacts A contact has a name, email, company, tags, custom field values and **channels**: one identity per network (an Instagram user, a Messenger user), each with its own subscription state. ```bash curl -X POST https://api.socialit.com/v1/contacts \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Jana Nováková", "email": "jana@example.com", "tags": ["vip"], "profile_id": "pro_8Lq2Vx7Bn4Mc1Zr8Tw3Ys6Hd0Kp" }' ``` - `POST /v1/contacts/bulk` imports up to 1,000 at once. - `POST /v1/contacts/{id}/tags` adds and removes tags; `GET /v1/contacts/tags` lists the tags in use. - `PUT /v1/contacts/{id}/fields/{slug}` sets a [custom field](/docs/api-reference/custom-fields/) (text, number, date, boolean, select). - Channels: `GET|POST /v1/contacts/{id}/channels`, `PATCH …/channels/{channelId}` to opt a channel in or out. Events: `contact.created`, `contact.updated`, `contact.deleted`, `contact.tag_added`, `contact.tag_removed`, `contact.field_changed`. ## Broadcasts 1. `POST /v1/broadcasts` with the sending `account_id`, a `name`, the `message` (text with `{{first_name}}`, `{{fields.}}` placeholders, attachments). 2. Choose recipients: `segment_filters` (tags, excluded tags, custom fields) or `POST /v1/broadcasts/{id}/recipients` with `contact_ids` or `phones`. `POST /v1/broadcasts/audience-preview` counts a segment first. 3. `POST /v1/broadcasts/{id}/send` now, or `…/schedule` with `scheduled_at`. Each recipient follows its channel's rules: Messenger and Instagram need the 24-hour window or a `HUMAN_AGENT` tag, otherwise the recipient is `skipped` with `outside_messaging_window`. Sends are paced per channel (for example Facebook 300, Instagram 100 messages per minute), adjustable with `rate_limit_per_minute`. `GET /v1/broadcasts/{id}/recipients` shows delivery per recipient. ## Sequences A sequence is an ordered list of steps on one account. Each step has a `delay_minutes`, a `message` and an optional `condition` on contact variables. - Create with `steps`, then `POST /v1/sequences/{id}/activate`. - `POST /v1/sequences/{id}/enroll` with `contact_ids` (up to 1,000); `DELETE …/enroll/{contactId}` takes one out. - By default a reply or an unsubscribe ends the enrollment (`exit_on_reply`, `exit_on_unsubscribe`). Events: `sequence.enrolled`, `sequence.step_sent`, `sequence.completed`, `sequence.exited`. ## Workflows A workflow is a graph of `nodes` and `edges` with exactly one `trigger` node. Triggers include `inbound_message`, `keyword`, `comment`, `story_mention`, `reaction`, `contact_tag_added`, `contact_field_changed`, `schedule`, `manual` and `api_call`. | Node | Does | |---|---| | `send_message`, `reply_to_comment`, `private_reply` | Send text, templates, media, buttons or quick replies | | `wait_for_reply`, `delay` | Wait for the contact or for time | | `condition`, `a_b_split` | Branch on variables (`contact.tags`, `contact.fields.`, `last_message`…) or randomly | | `set_variable`, `add_tag`, `remove_tag`, `set_field` | Update the run or the contact | | `http_request` | Call your API (HTTPS, response saved for later nodes) | | `ai` | Generate a reply with Claude (`system_prompt`, `user_prompt_template`) | | `assign_conversation`, `handoff` | Hand the conversation to a person | | `enroll_sequence`, `end` | Chain into a sequence, or stop | `GET /v1/workflows/node-types` returns the full catalog with config schemas. Edit the graph while the workflow is `draft` or `paused`; every change is a new version (`/versions`, `…/restore`). Start runs with `POST /v1/workflows/{id}/trigger` (API trigger, honours `Idempotency-Key`) or `…/executions` (test runs), and inspect them with `…/executions/{executionId}/events`. Events: `workflow.triggered`, `workflow.completed`, `workflow.failed`. ## Comment automations Comment-to-DM, ManyChat style: when someone comments a keyword on a post (or anywhere on the account), Socialit replies publicly and sends a DM. ```json { "account_id": "sa_instagram…", "name": "Price list", "post_id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd", "keywords": ["price", "cena"], "dm_message": "Hi {{first_name}}! Here is our price list.", "buttons": [{ "type": "url", "title": "Open", "url": "https://acme.example/prices" }], "comment_reply": "Sent you a DM 📩", "repeat_policy": { "mode": "once" } } ``` - Instagram and Facebook get the public reply and the DM; TikTok, Threads, LinkedIn, YouTube, Bluesky and Reddit get the public reply only. - Instagram adds `story_reply`, `story_mention` and `live_comment` triggers, follower gates and audience filters. - `post_id` arms the automation when a scheduled Socialit post publishes. Links in buttons are tracked, and `click_tag` tags the contact on click. - `GET /v1/comment-automations/{id}/logs` shows every trigger, kept 90 days. A matching comment automation answers before any `comment` workflow, and messages sent by automations never trigger workflows. ## Support assistant `POST /v1/support/runs` asks the Socialit support assistant a question (with optional `context` such as a `post_id` or `request_id`) and returns `202` with a run to poll at `GET /v1/support/runs/{id}`. Answers cite the docs they used. --- Source: https://socialit.com/docs/crm-automations/ # Focus mode > Everything a network's API allows for one connected account, through a manifest, generic operations and typed per-network endpoints, with scope upgrades on demand. Publishing and the inbox cover what every network has in common. **Focus mode** covers the rest: everything a network's API allows for one connected account, such as YouTube playlists, captions and live broadcasts, Reddit mod queues, Discord roles or Mastodon filters. The app renders it as a full-screen workspace per account (see [UI modes](/docs/ui-modes/)); the API exposes the same resources in two shapes. | Shape | Reference | MCP toolset | Use it for | |---|---|---|---| | **Generic operations** | [Focus](/docs/api-reference/focus/) (10 endpoints) | `focus` | Building a UI from the manifest, one integration for every network | | **Typed operations** | [Focus · YouTube](/docs/api-reference/focus-youtube/), [Focus · X](/docs/api-reference/focus-x/), … (one tag per network) | `focus_youtube`, `focus_x`, … | Documented, typed calls and SDKs; agents working on one network | Both run through the same dispatcher, return the same shapes and need the same scopes. ## 1. Read the manifest ```bash curl https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/focus \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` The manifest lists the account's **resources** (`videos`, `live-broadcasts`, `playlists`, …). Each one has JSON-schema `fields`, the operations it supports (`list`, `get`, `create`, `update`, `delete`) with their query and body schemas, named `actions` (`go-live`, `set-thumbnail`, …), whether it is a `singleton`, and its `typed_path`. `GET /v1/focus/platforms` lists the networks with a focus module and their toolsets. ## 2. Call a resource Generic routes take the resource key and action name from the manifest: | Operation | Generic | Typed (YouTube example) | |---|---|---| | List | `GET /v1/accounts/{accountId}/focus/{resource}` | `GET /v1/accounts/{accountId}/youtube/videos` | | Get | `GET …/focus/{resource}/{itemId}` | `GET …/youtube/videos/{itemId}` | | Create | `POST …/focus/{resource}` | `POST …/youtube/playlists` | | Update | `PATCH …/focus/{resource}/{itemId}` | `PATCH …/youtube/videos/{itemId}` | | Delete | `DELETE …/focus/{resource}/{itemId}` | `DELETE …/youtube/playlists/{itemId}` | | Item action | `POST …/focus/{resource}/{itemId}/{action}` | `POST …/youtube/live-broadcasts/{itemId}/go-live` | | Collection action | `POST …/focus/{resource}/-/{action}` | `POST …/youtube/videos/{action}` | Singleton resources (a channel's settings, a Discord server's welcome screen) have no item ID: `GET`, `PATCH` and `DELETE` the resource path itself. - Query parameters and bodies are validated against the resource's schemas (`422 validation_failed` with `errors` per field). Fields with `format: "media-id"` take Socialit media IDs (`med_…`). - Lists use cursors: pass `next_cursor` back as `cursor`. - Items are returned as the network object, in snake_case, never stripped of extra fields. - Typed operation IDs and MCP tools follow `--`, such as `youtube-videos-list` or `youtube-live-broadcasts-go-live`. ## 3. Upgrade scopes when you need them Accounts connect with the **core** scopes for publishing, inbox and analytics. Focus resources often need more. The manifest tells you: - `resources[].available` is `false` when the account lacks the resource's scopes, and `resources[].missing_scopes` lists them. - The top-level `missing_scopes` is the union, and `reconnect_url` is a ready-made link: `GET /v1/connect/youtube?reconnect_account_id=sa_…&scope_set=focus`. - Calling a resource without its scopes answers `403 missing_scopes` with `missing_scopes` and `reconnect_url`. Send the user through `reconnect_url` (it keeps the account, its profile and history, and never counts against your allowance). New connections can ask for everything up front with `scope_set=focus` on [`GET /v1/connect/{platform}`](/docs/connecting-accounts/#oauth-redirect). > **Network limits apply:** Focus calls go straight to the network, so its quotas apply: YouTube quota units, X pay-per-use credits (`402 x_credits_required` without prepaid credits), Reddit QPM. Rate-limited calls answer `429 platform_rate_limited` with `Retry-After`. ## MCP The generic tools are in toolset `focus`; each network's typed tools are in `focus_`. There are nearly 2,000 typed tools, so select the networks you need: ```text https://api.socialit.com/mcp?toolsets=focus,focus_youtube ``` See [MCP server](/docs/mcp/#toolsets). --- Source: https://socialit.com/docs/focus-mode/ # Unified inbox > Read and answer DMs, comments, reviews and mentions from every network through one API, and receive them in real time with webhooks. The inbox brings four kinds of activity from every connected account into one model, in the [Inbox](/docs/api-reference/inbox/) reference (MCP toolset `inbox`): | Kind | Networks | Endpoints | |---|---|---| | **Conversations and messages** | Facebook, Instagram, X, Bluesky, Reddit, Discord, Mastodon, TikTok business | `/v1/inbox/conversations…` | | **Comments** | Most publishing networks | `/v1/inbox/posts…`, `/v1/inbox/comments…` | | **Reviews** | Google Business Profile, Facebook | `/v1/inbox/reviews…` | | **Mentions** | Where the network reports them | `/v1/inbox/mentions…` | You only see items of accounts in profiles you can access. ## Conversations ```bash curl "https://api.socialit.com/v1/inbox/conversations?status=open&platform=instagram&unread=true" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Filter by `profile_id`, `account_id`, `platform`, `status` (`open`, `archived`, `snoozed`), `folder` (`inbox` or `requests` for Facebook and Instagram message requests), `assignee_id`, `label` and `unread`. `GET /v1/inbox/conversations/search?q=…` searches messages and participants. Triage with `PATCH /v1/inbox/conversations/{conversationId}`: `status`, `snoozed_until`, `assignee_id`, `labels` and `contact_id`. Mark read with `POST …/read` (sends read receipts where the network supports them). ## Send messages ```bash curl -X POST https://api.socialit.com/v1/inbox/conversations/conv_4Xb1Nq8Lm2Vc7Rt9Ys3Kd6Hp0Zw/messages \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: reply-4711" \ -H "Content-Type: application/json" \ -d '{ "text": "Yes, we ship to Canada!", "quick_replies": [{ "title": "Track my order", "payload": "TRACK" }] }' ``` Messages take `text`, `media_ids` (upload with [Media](/docs/api-reference/media/)) or `attachment_url`, and network features such as `buttons`, `quick_replies` and `reply_to`. Start a new thread, such as a cold DM, with `POST /v1/inbox/conversations`. Socialit enforces each network's messaging rules. Messenger and Instagram allow free-form replies within 24 hours of the customer's last message; after that Meta needs a `message_tag`. Delete, react and fetch attachments under `…/messages/{messageId}`. ## Comments - `GET /v1/inbox/posts` lists posts with comments; `GET /v1/inbox/posts/{postId}/comments` reads a post's comments live. `postId` can be an inbox post, a Socialit post (`pst_…`) or a network post ID with `account_id`. - `GET /v1/inbox/comments` is a feed across every post, with `status`, `read`, `hidden` and assignment filters. - Act on a comment: `…/replies`, `…/hide`, `…/like`, `…/pin` (TikTok), `…/moderation` (YouTube held-for-review), `DELETE`, and `…/private-reply`, which answers a Facebook or Instagram commenter by DM. To answer comments automatically (comment-to-DM), see [CRM and automations](/docs/crm-automations/#comment-automations). ## Reviews and mentions `GET /v1/inbox/reviews` returns reviews with a rating `summary`; `POST /v1/inbox/reviews/{reviewId}/reply` replies (or replaces the reply), and `DELETE …/reply` removes it on Google Business Profile. Mentions are listed at `GET /v1/inbox/mentions` and answered with `POST /v1/inbox/mentions/reply`. ## Real-time ingestion with webhooks Socialit receives the networks' own webhooks (Meta, X, LinkedIn, TikTok, Google Business, Discord, YouTube) at its own endpoints, deduplicates them, normalizes them and stores them. Networks without push (Reddit, Bluesky, Mastodon, Threads, LinkedIn organizations) are polled every 5 to 30 minutes. Either way, your app gets one stream of [webhook events](/docs/api-reference/webhook-events/#events-inbox): | Event | Payload (`data`) | |---|---| | `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`, `message.edited`, `message.deleted` | `{ message, conversation, account }` | | `reaction.received` | `{ reaction, message, conversation, account }` | | `conversation.created`, `conversation.updated` | `{ conversation, account }` (+ `changes`) | | `comment.received`, `comment.replied`, `comment.hidden`, `comment.unhidden`, `comment.deleted` | `{ comment, post, account }` | | `review.received`, `review.updated`, `review.replied` | `{ review, account }` | | `mention.received` | `{ mention, account }` | Create an endpoint with `POST /v1/webhooks` and `events: ["message.received", "comment.received"]`, and verify signatures as described in [Webhooks](/docs/webhooks/). The first sync of a new account imports history silently: no events, nothing unread. Need it sooner? `POST /v1/inbox/sync` queues an immediate poll for the polled networks, and `GET /v1/inbox/counts` returns unread and open counters for badges. ## Account messaging settings Configure the entry points of a conversation per account: Messenger persistent menu, get-started button, greeting and ice breakers, and Instagram ice breakers (`/v1/accounts/{accountId}/messenger-menu`, `…/instagram-ice-breakers`, …). ## Contacts Every sender becomes a [contact](/docs/crm-automations/#contacts) with channels per network, tags and custom fields. Link a conversation to a contact with `contact_id`. --- Source: https://socialit.com/docs/inbox/ # ChatGPT > Connect ChatGPT to the Socialit MCP server as a custom connector. 1. In ChatGPT, open **Settings → Apps & Connectors → Advanced** and turn on **Developer mode** (available on plans that support custom connectors). 2. Choose **Create**, name the connector `Socialit` and enter `https://api.socialit.com/mcp` as the server URL, with OAuth authentication. 3. Sign in to Socialit and approve the workspaces and scopes. In a chat, enable the Socialit connector from the tools menu. ChatGPT asks for confirmation before tools that change data, such as creating a post. > **Tip:** Start with `?read_only=true` on the URL while you try it out, then remove it when you want ChatGPT to schedule posts. --- Source: https://socialit.com/docs/mcp/chatgpt/ # Claude > Connect Claude, Claude Desktop and Claude Code to the Socialit MCP server. ## Claude and Claude Desktop 1. Open **Settings → Connectors** and choose **Add custom connector**. 2. Name it `Socialit` and paste `https://api.socialit.com/mcp`. 3. Select **Connect**, sign in to Socialit and approve the workspaces and scopes. The Socialit tools appear in the tools menu of a chat. Try: *"List my scheduled posts for next week and move the LinkedIn ones to 9:00."* ## Claude Code ```bash claude mcp add --transport http socialit https://api.socialit.com/mcp ``` Run `/mcp` in Claude Code to sign in. To use an API key instead of OAuth: ```bash claude mcp add --transport http socialit https://api.socialit.com/mcp \ --header "Authorization: Bearer $SOCIALIT_API_KEY" ``` --- Source: https://socialit.com/docs/mcp/claude/ # Cursor > Connect Cursor to the Socialit MCP server. Add Socialit to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): ```json title="mcp.json" { "mcpServers": { "socialit": { "url": "https://api.socialit.com/mcp" } } } ``` Cursor opens the Socialit sign-in the first time a tool is used. With an API key instead: ```json title="mcp.json" { "mcpServers": { "socialit": { "url": "https://api.socialit.com/mcp", "headers": { "Authorization": "Bearer sk_live_…" } } } } ``` Keep keys out of shared repositories: use the project file only with environment-specific secrets, or the global file. --- Source: https://socialit.com/docs/mcp/cursor/ # MCP server > Connect Claude, Cursor, ChatGPT and other AI agents to Socialit through the remote MCP server at /mcp, with OAuth or an API key, and pick the toolsets they need. Socialit runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server. Every operation of the REST API is also an MCP tool, so an agent can draft and schedule posts, answer the inbox, read analytics, run broadcasts and manage accounts with the same validation, rate limits and permissions as the API. Tool calls run through the real `/v1` endpoints, so responses and errors are identical. | | | |---|---| | URL | `https://api.socialit.com/mcp` | | Transport | Streamable HTTP (stateless) | | Auth | OAuth 2.1 with PKCE and dynamic client registration, or `Authorization: Bearer sk_live_…` | | Plans | Every plan, using the plan's API request budget | ## Connect a client - [Claude](/docs/mcp/claude/)Claude, Claude Desktop and Claude Code. - [Cursor](/docs/mcp/cursor/)One entry in mcp.json. - [ChatGPT](/docs/mcp/chatgpt/)Custom connector in developer mode. Any other client that supports remote MCP servers over Streamable HTTP works the same way: give it the URL and sign in, or send an API key header. ## OAuth or API key - **OAuth** is best for people: the client opens a Socialit consent screen, you pick the workspaces and scopes (`read`, `write`, `admin`), and you can revoke the connection in **Account → Connected apps**. The agent acts with your role and profile access. OAuth connections can reach several workspaces: they get `list-workspaces` and `switch-workspace` tools and a `workspace` argument on every tool. - **API keys** are best for servers and scripts. Use a `read` key for reporting agents, and restrict a key to some profiles to fence an agent in. Everyone gets `get-current-workspace`. Tools the credential can't call are hidden from `tools/list`. ## Tool names A tool is named after its operation ID in kebab-case: `createPost` is `create-post`, `listConversations` is `list-conversations`. Every endpoint in the [API reference](/docs/api-reference/) shows its tool name and toolset, and an **MCP** tab with a ready-made `tools/call` request. The input schema merges the path, query and body parameters; list tools also take `filters: [{ field, condition, value }]`. Tools are annotated as read-only, destructive, idempotent or open-world. ## Toolsets Large tool lists cost tokens and attention. Narrow them with query parameters on the server URL (or the `X-MCP-Toolsets` and `X-MCP-Readonly` headers): - `?toolsets=posts,inbox` exposes only those toolsets. - `?read_only=true` exposes only tools that don't change anything. ```text https://api.socialit.com/mcp?toolsets=posts,media,accounts,analytics&read_only=true ``` ### Focus mode toolsets (opt in) [Focus mode](/docs/focus-mode/) adds a typed toolset per network, nearly 2,000 tools in total. Select only the networks your agent works on, next to the generic `focus` toolset: ```text https://api.socialit.com/mcp?toolsets=focus,focus_youtube,focus_reddit ``` ## Good practice - Ask the agent to create **drafts** for anything public and review them in the app before they go out. - Use profile-restricted keys or a read-only connection for agents that only report. - Give agents the toolsets they need instead of everything. - Every tool call appears in the workspace request logs and activity with the client's name. --- Source: https://socialit.com/docs/mcp/ # Migrating from Zernio > Move an integration from the Zernio API to Socialit, with every Zernio endpoint mapped to its Socialit equivalent and MCP tool. Socialit replaces the Zernio API endpoint for endpoint: every Zernio endpoint in the map at the end of this page has a Socialit equivalent. Most migrations are a base URL change, a key change and a few renamed fields. The map is generated from the API itself: every Socialit operation declares the Zernio operations it replaces (the `x-zernio` extension in our [OpenAPI document](https://api.socialit.com/v1/openapi.json)). ## What changes | | Zernio | Socialit | |---|---|---| | Base URL | `…/v1` | `https://api.socialit.com/v1` | | Auth | API key | `Authorization: Bearer sk_live_…`, or OAuth 2.1 with PKCE ([Authentication](/docs/authentication/)) | | Casing | camelCase in places | snake_case everywhere | | IDs | Mixed | Prefixed OIDs: `pst_…` posts, `sa_…` accounts, `pro_…` profiles ([Objects and IDs](/docs/concepts/objects/)) | | Updates | `PUT` | `PATCH`; `PUT` is accepted as an alias wherever Zernio used it | | Lists | Varies | One envelope with `page`, `limit`, `has_more`, `next_page_url` ([Pagination](/docs/api-reference/pagination/)) | | Errors | Varies | One envelope: `{ error: { type, code, message, param, errors }, request_id }` ([Errors](/docs/api-reference/errors/)) | | Retries | – | `Idempotency-Key` on every create and send ([Idempotency](/docs/api-reference/idempotency/)) | | AI agents | – | Every operation is an [MCP tool](/docs/mcp/) | ## Migrate step by step 1. **Create an API key** in **Manage → API keys** (or `POST /v1/api-keys`). Restrict it to profiles if the integration serves one client. 2. **Reconnect accounts** with [Connecting accounts](/docs/connecting-accounts/) (`GET /v1/connect/{platform}`, or hosted connect links for your customers). Zernio's `/v1/connect/*` pickers have Socialit equivalents with the same bodies. 3. **Swap endpoints** using the map below. Paths keep their shape: `GET /v1/posts/{postId}` becomes `GET /v1/posts/{id}`. 4. **Rename fields to snake_case** and use the new names where they differ, for example posts use `account_ids`, `platform_options`, `scheduled_at` and `publish_now`. Each endpoint's reference lists its fields. 5. **Move webhooks** to `POST /v1/webhooks` and verify the `X-Socialit-Signature` HMAC ([Webhooks](/docs/webhooks/)). Event types are listed in [Webhook events](/docs/api-reference/webhook-events/); where a Zernio event had a different name, its description says so. 6. **Test** with a read-only key first, then switch writes. > **Let an agent do it:** Point Claude, Cursor or another MCP client at `https://api.socialit.com/mcp` and this page (`/docs/migrating-from-zernio.md`): the map below gives it the Socialit endpoint and MCP tool for every Zernio call in your code. ## Endpoint map Each of the 568 Zernio endpoints below has a Socialit equivalent. ### Validate | Zernio | Socialit | MCP tool | |---|---|---| | `POST /v1/tools/validate/post-length` | `POST /tools/validate/post-length` | `validate-post-length` | | `POST /v1/tools/validate/post` | `POST /tools/validate/post` | `validate-post` | | `POST /v1/tools/validate/media` | `POST /tools/validate/media` | `validate-media-url` | | `GET /v1/tools/validate/subreddit` | `GET /tools/validate/subreddit`
`GET /accounts/{accountId}/reddit/subreddits` | `validate-subreddit` `reddit-subreddits-list` | ### Analytics | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/analytics` | `GET /analytics`
`GET /analytics/posts/{postId}`
`GET /accounts/{accountId}/snapchat/profile-insights`
`GET /accounts/{accountId}/snapchat/content-insights`
`GET /accounts/{accountId}/snapchat/asset-insights`
`GET /accounts/{accountId}/threads/post-insights`
`GET /accounts/{accountId}/tiktok/post-insights`
`GET /accounts/{accountId}/x/post-metrics` | `list-post-analytics` `get-post-analytics` `snapchat-profile-insights-list` `snapchat-content-insights-list` `snapchat-asset-insights-list` `threads-post-insights-list` `tiktok-post-insights-list` `x-post-metrics-list` | | `GET /v1/analytics/delta` | `GET /analytics/delta` | `get-analytics-delta` | | `GET /v1/analytics/youtube/channel-insights` | `GET /analytics/youtube/channel-insights`
`GET /accounts/{accountId}/youtube/analytics-overview` | `get-youtube-channel-insights` `youtube-analytics-overview-get` | | `GET /v1/analytics/linkedin/org-aggregate-analytics` | `GET /analytics/linkedin/org-aggregate-analytics`
`GET /accounts/{accountId}/linkedin/org-aggregate` | `get-linkedin-org-analytics` `linkedin-org-aggregate-get` | | `GET /v1/analytics/tiktok/account-insights` | `GET /analytics/tiktok/account-insights`
`GET /accounts/{accountId}/tiktok/account-counters` | `get-tiktok-account-insights` `tiktok-account-counters-get` | | `GET /v1/analytics/youtube/daily-views` | `GET /analytics/youtube/daily-views`
`GET /accounts/{accountId}/youtube/analytics-video` | `get-youtube-daily-views` `youtube-analytics-video-get` | | `GET /v1/analytics/youtube/video-retention` | `GET /analytics/youtube/video-retention`
`GET /accounts/{accountId}/youtube/analytics-retention` | `get-youtube-video-retention` `youtube-analytics-retention-get` | | `GET /v1/analytics/facebook/page-insights` | `GET /analytics/facebook/page-insights`
`GET /accounts/{accountId}/facebook/page-insights` | `get-facebook-page-insights` `facebook-page-insights-list` | | `GET /v1/analytics/facebook/post-earnings` | `GET /analytics/facebook/post-earnings`
`GET /accounts/{accountId}/facebook/monetization` | `get-facebook-post-earnings` `facebook-monetization-list` | | `GET /v1/analytics/instagram/account-insights` | `GET /analytics/instagram/account-insights`
`GET /accounts/{accountId}/instagram/account-insights` | `get-instagram-account-insights` `instagram-account-insights-get` | | `GET /v1/analytics/instagram/follower-history` | `GET /analytics/instagram/follower-history`
`GET /accounts/{accountId}/instagram/follower-history` | `get-instagram-follower-history` `instagram-follower-history-get` | | `GET /v1/analytics/facebook/demographics` | `GET /analytics/facebook/demographics`
`GET /accounts/{accountId}/facebook/demographics` | `get-facebook-demographics` `facebook-demographics-list` | | `GET /v1/analytics/instagram/demographics` | `GET /analytics/instagram/demographics`
`GET /accounts/{accountId}/instagram/audience` | `get-instagram-demographics` `instagram-audience-get` | | `GET /v1/analytics/instagram/online-followers` | `GET /analytics/instagram/online-followers`
`GET /accounts/{accountId}/instagram/online-followers` | `get-instagram-online-followers` `instagram-online-followers-get` | | `GET /v1/analytics/youtube/demographics` | `GET /analytics/youtube/demographics`
`GET /accounts/{accountId}/youtube/analytics-audience`
`GET /accounts/{accountId}/youtube/analytics-demographics` | `get-youtube-demographics` `youtube-analytics-audience-get` `youtube-analytics-demographics-get` | | `GET /v1/analytics/daily-metrics` | `GET /analytics/daily-metrics`
`GET /accounts/{accountId}/threads/account-insights` | `get-daily-metrics` `threads-account-insights-get` | | `GET /v1/analytics/dashboard` | `GET /analytics/dashboard` | `get-analytics-dashboard` | | `GET /v1/analytics/best-time` | `GET /analytics/best-time` | `get-best-time-to-post` | | `GET /v1/analytics/content-decay` | `GET /analytics/content-decay` | `get-content-decay` | | `GET /v1/analytics/posting-frequency` | `GET /analytics/posting-frequency` | `get-posting-frequency` | | `GET /v1/analytics/post-timeline` | `GET /analytics/post-timeline` | `get-post-timeline` | | `GET /v1/analytics/googlebusiness/performance` | `GET /analytics/googlebusiness/performance`
`GET /accounts/{accountId}/google-business/performance` | `get-google-business-performance` `google-business-performance-list` | | `GET /v1/analytics/googlebusiness/search-keywords` | `GET /analytics/googlebusiness/search-keywords`
`GET /accounts/{accountId}/google-business/search-keywords` | `get-google-business-search-keywords` `google-business-search-keywords-list` | | `POST /v1/posts/sync-external` | `POST /posts/sync-external`
`POST /accounts/{accountId}/linkedin/posts`
`POST /accounts/{accountId}/threads/posts` | `sync-external-posts` `linkedin-posts-create` `threads-posts-create` | | `GET /v1/accounts/{accountId}/linkedin-aggregate-analytics` | `GET /accounts/{accountId}/linkedin/aggregate-analytics`
`GET /accounts/{accountId}/linkedin/member-aggregate` | `get-linkedin-aggregate-analytics` `linkedin-member-aggregate-get` | | `GET /v1/accounts/{accountId}/linkedin-post-analytics` | `GET /accounts/{accountId}/linkedin/post-analytics` | `get-linkedin-post-analytics` | | `GET /v1/accounts/{accountId}/linkedin-post-reactions` | `GET /accounts/{accountId}/linkedin/post-reactions`
`GET /accounts/{accountId}/linkedin/reactions` | `get-linkedin-post-reactions` `linkedin-reactions-list` | | `GET /v1/accounts/{accountId}/facebook-post-reactions` | `GET /accounts/{accountId}/facebook/post-reactions`
`GET /accounts/{accountId}/facebook/reactions` | `get-facebook-post-reactions` `facebook-reactions-list` | ### Inbox Analytics | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/analytics/inbox/volume` | `GET /analytics/inbox/volume` | `get-inbox-volume` | | `GET /v1/analytics/inbox/heatmap` | `GET /analytics/inbox/heatmap` | `get-inbox-heatmap` | | `GET /v1/analytics/inbox/source-breakdown` | `GET /analytics/inbox/source-breakdown` | `get-inbox-source-breakdown` | | `GET /v1/analytics/inbox/response-time` | `GET /analytics/inbox/response-time` | `get-inbox-response-time` | | `GET /v1/analytics/inbox/top-accounts` | `GET /analytics/inbox/top-accounts` | `get-inbox-top-accounts` | | `GET /v1/analytics/inbox/conversations` | `GET /analytics/inbox/conversations` | `list-conversation-analytics` | | `GET /v1/analytics/inbox/conversations/{conversationId}` | `GET /analytics/inbox/conversations/{conversationId}` | `get-conversation-analytics` | ### Account Groups | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/account-groups` | `GET /account-groups` | `list-account-groups` | | `POST /v1/account-groups` | `POST /account-groups` | `create-account-group` | | `PUT /v1/account-groups/{groupId}` | `PATCH /account-groups/{id}` | `update-account-group` | | `DELETE /v1/account-groups/{groupId}` | `DELETE /account-groups/{id}` | `delete-account-group` | ### Media | Zernio | Socialit | MCP tool | |---|---|---| | `POST /v1/media/presign` | `POST /media/presign` | `presign-media-upload` | ### Reddit Search | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/reddit/search` | `GET /accounts/{accountId}/reddit/search` | `search-reddit` | | `GET /v1/reddit/feed` | `GET /accounts/{accountId}/reddit/feed` | `get-reddit-feed` | | `GET /v1/reddit/comments/{postId}` | `GET /accounts/{accountId}/reddit/posts/{postId}/comments`
`GET /accounts/{accountId}/reddit/post-comments` | `get-reddit-post-comments` `reddit-post-comments-list` | ### Usage | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/billing` | `GET /billing` | `get-billing` | | `GET /v1/billing/x-pricing` | `GET /billing/x-pricing` | `get-x-pricing` | | `GET /v1/usage` | `GET /usage` | `get-usage` | | `GET /v1/usage-stats` | `GET /usage` | `get-usage` | ### Posts | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/posts` | `GET /posts` | `list-posts` | | `POST /v1/posts` | `POST /posts`
`POST /accounts/{accountId}/google-business/posts`
`POST /accounts/{accountId}/snapchat/stories`
`POST /accounts/{accountId}/snapchat/saved-stories`
`POST /accounts/{accountId}/snapchat/spotlights`
`POST /accounts/{accountId}/threads/posts`
`POST /accounts/{accountId}/x/posts`
`POST /accounts/{accountId}/x/threads`
`POST /accounts/{accountId}/x/polls`
`POST /accounts/{accountId}/x/articles` | `create-post` `google-business-posts-create` `snapchat-stories-create` `snapchat-saved-stories-create` `snapchat-spotlights-create` `threads-posts-create` `x-posts-create` `x-threads-create` `x-polls-create` `x-articles-create` | | `GET /v1/posts/{postId}` | `GET /posts/{id}` | `get-post` | | `PUT /v1/posts/{postId}` | `PATCH /posts/{id}` | `update-post` | | `DELETE /v1/posts/{postId}` | `DELETE /posts/{id}` | `delete-post` | | `POST /v1/posts/bulk-upload` | `POST /posts/bulk-upload` | `bulk-upload-posts` | | `POST /v1/posts/{postId}/retry` | `POST /posts/{id}/retry` | `retry-post` | | `POST /v1/posts/{postId}/unpublish` | `POST /posts/{id}/unpublish`
`POST /accounts/{accountId}/bluesky/posts`
`POST /accounts/{accountId}/facebook/posts`
`POST /accounts/{accountId}/google-business/posts`
`POST /accounts/{accountId}/linkedin/posts`
`POST /accounts/{accountId}/reddit/my-posts`
`POST /accounts/{accountId}/threads/posts`
`POST /accounts/{accountId}/x/posts`
`POST /accounts/{accountId}/youtube/videos` | `unpublish-post` `bluesky-posts-create` `facebook-posts-create` `google-business-posts-create` `linkedin-posts-create` `reddit-my-posts-create` `threads-posts-create` `x-posts-create` `youtube-videos-create` | | `POST /v1/posts/{postId}/edit` | `POST /posts/{id}/edit`
`POST /accounts/{accountId}/facebook/posts`
`POST /accounts/{accountId}/google-business/posts`
`POST /accounts/{accountId}/linkedin/posts`
`POST /accounts/{accountId}/reddit/my-posts`
`POST /accounts/{accountId}/x/posts`
`POST /accounts/{accountId}/youtube/videos` | `edit-published-post` `facebook-posts-create` `google-business-posts-create` `linkedin-posts-create` `reddit-my-posts-create` `x-posts-create` `youtube-videos-create` | | `POST /v1/posts/{postId}/update-metadata` | `POST /posts/{id}/update-metadata`
`POST /accounts/{accountId}/youtube/videos` | `update-post-metadata` `youtube-videos-create` | ### Users | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/users` | `GET /users` | `list-users` | | `GET /v1/users/{userId}` | `GET /users/{id}` | `get-user` | ### Profiles | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/profiles` | `GET /profiles` | `list-profiles` | | `POST /v1/profiles` | `POST /profiles` | `create-profile` | | `GET /v1/profiles/{profileId}` | `GET /profiles/{id}` | `get-profile` | | `PUT /v1/profiles/{profileId}` | `PATCH /profiles/{id}` | `update-profile` | | `DELETE /v1/profiles/{profileId}` | `DELETE /profiles/{id}` | `delete-profile` | ### Accounts | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts` | `GET /accounts` | `list-accounts` | | `GET /v1/accounts/follower-stats` | `GET /accounts/follower-stats`
`GET /accounts/{accountId}/threads/account-insights`
`GET /accounts/{accountId}/x/account-overview` | `get-follower-stats` `threads-account-insights-get` `x-account-overview-get` | | `PUT /v1/accounts/{accountId}` | `PATCH /accounts/{id}` | `update-account` | | `PATCH /v1/accounts/{accountId}` | `PATCH /accounts/{id}` | `update-account` | | `DELETE /v1/accounts/{accountId}` | `DELETE /accounts/{id}` | `disconnect-account` | | `GET /v1/accounts/health` | `GET /accounts/health` | `get-accounts-health` | | `GET /v1/accounts/{accountId}/health` | `GET /accounts/{id}/health` | `get-account-health` | | `GET /v1/accounts/{accountId}/posts` | `GET /accounts/{id}/posts`
`GET /accounts/{accountId}/bluesky/posts`
`GET /accounts/{accountId}/instagram/media`
`GET /accounts/{accountId}/linkedin/posts`
`GET /accounts/{accountId}/reddit/my-posts`
`GET /accounts/{accountId}/threads/posts`
`GET /accounts/{accountId}/tiktok/videos`
`GET /accounts/{accountId}/x/posts` | `list-account-platform-posts` `bluesky-posts-list` `instagram-media-list` `linkedin-posts-list` `reddit-my-posts-list` `threads-posts-list` `tiktok-videos-list` `x-posts-list` | | `GET /v1/accounts/{accountId}/follow-status/{userId}` | `GET /accounts/{accountId}/follow-status/{userId}`
`GET /accounts/{accountId}/instagram/people/{itemId}` | `get-instagram-follow-status` `instagram-people-get` | | `GET /v1/accounts/{accountId}/tiktok/commercial-music` | `GET /accounts/{accountId}/tiktok/commercial-music` | `list-tiktok-commercial-music` | | `GET /v1/accounts/{accountId}/tiktok/locations` | `GET /accounts/{accountId}/tiktok/locations` | `search-tiktok-locations` | | `GET /v1/accounts/{accountId}/tiktok/creator-info` | `GET /accounts/{accountId}/tiktok/creator-info` | `get-tiktok-creator-info` | | `GET /v1/accounts/{accountId}/business-partners` | `GET /accounts/{accountId}/business-partners`
`GET /accounts/{accountId}/facebook/business-partners` | `list-facebook-business-partners` `facebook-business-partners-list` | | `POST /v1/accounts/{accountId}/business-partners` | `POST /accounts/{accountId}/business-partners`
`POST /accounts/{accountId}/facebook/business-partners` | `share-facebook-page-with-partner` `facebook-business-partners-create` | | `DELETE /v1/accounts/{accountId}/business-partners` | `DELETE /accounts/{accountId}/business-partners`
`DELETE /accounts/{accountId}/facebook/business-partners/{itemId}` | `revoke-facebook-business-partner` `facebook-business-partners-delete` | | `GET /v1/accounts/{accountId}/bluesky-settings` | `GET /accounts/{accountId}/bluesky-settings`
`GET /accounts/{accountId}/bluesky/posting-defaults` | `get-bluesky-settings` `bluesky-posting-defaults-get` | | `PATCH /v1/accounts/{accountId}/bluesky-settings` | `PATCH /accounts/{accountId}/bluesky-settings`
`PATCH /accounts/{accountId}/bluesky/posting-defaults` | `update-bluesky-settings` `bluesky-posting-defaults-update` | ### API Keys | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/auth/verify` | `GET /auth/verify` | `verify-credential` | | `GET /v1/api-keys` | `GET /api-keys` | `list-api-keys` | | `POST /v1/api-keys` | `POST /api-keys` | `create-api-key` | | `DELETE /v1/api-keys/{keyId}` | `DELETE /api-keys/{id}` | `delete-api-key` | ### Feedback | Zernio | Socialit | MCP tool | |---|---|---| | `POST /v1/feedback` | `POST /feedback` | `submit-feedback` | ### Connected Apps | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/me/connected-apps` | `GET /me/connected-apps` | | | `DELETE /v1/me/connected-apps/{clientId}` | `DELETE /me/connected-apps/{clientId}` | | ### Invites | Zernio | Socialit | MCP tool | |---|---|---| | `POST /v1/invite/tokens` | `POST /invite/tokens` | `create-invite-token` | ### Connect | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/connect/{platform}` | `GET /connect/{platform}` | `get-connect-url` | | `POST /v1/connect/{platform}` | `POST /connect/{platform}` | `complete-connect` | | `GET /v1/connect/{platform}/ads` | `GET /connect/{platform}/ads` | `connect-ads` | | `GET /v1/connect/meta-ads/callback` | `GET /connect/meta-ads/callback` | | | `PATCH /v1/connect/tiktok-ads` | `PATCH /connect/tiktok-ads` | `set-tiktok-ads-brand-identity` | | `GET /v1/connect/facebook/select-page` | `GET /connect/facebook/select-page`
`GET /accounts/{accountId}/facebook/pages` | `list-facebook-page-connect-targets` `facebook-pages-list` | | `POST /v1/connect/facebook/select-page` | `POST /connect/facebook/select-page`
`POST /accounts/{accountId}/facebook/pages/{itemId}/select` | `select-facebook-page-connect-targets` `facebook-pages-select` | | `GET /v1/connect/instagram/select-account` | `GET /connect/instagram/select-account` | `list-instagram-account-connect-targets` | | `POST /v1/connect/instagram/select-account` | `POST /connect/instagram/select-account` | `select-instagram-account-connect-targets` | | `GET /v1/connect/googlebusiness/locations` | `GET /connect/googlebusiness/locations`
`GET /accounts/{accountId}/google-business/locations` | `list-google-business-location-connect-targets` `google-business-locations-list` | | `POST /v1/connect/googlebusiness/select-location` | `POST /connect/googlebusiness/select-location` | `select-google-business-location-connect-targets` | | `GET /v1/connect/pending-data` | `GET /connect/pending-data` | `get-pending-connection` | | `GET /v1/connect/linkedin/organizations` | `GET /connect/linkedin/organizations` | `list-linkedin-organization-connect-targets` | | `POST /v1/connect/linkedin/select-organization` | `POST /connect/linkedin/select-organization` | `select-linkedin-organization-connect-targets` | | `GET /v1/connect/pinterest/select-board` | `GET /connect/pinterest/select-board` | `list-pinterest-board-connect-targets` | | `POST /v1/connect/pinterest/select-board` | `POST /connect/pinterest/select-board` | `select-pinterest-board-connect-targets` | | `GET /v1/connect/snapchat/select-profile` | `GET /connect/snapchat/select-profile`
`GET /accounts/{accountId}/snapchat/profiles` | `list-snapchat-profile-connect-targets` `snapchat-profiles-list` | | `POST /v1/connect/snapchat/select-profile` | `POST /connect/snapchat/select-profile`
`GET /accounts/{accountId}/snapchat/profiles` | `select-snapchat-profile-connect-targets` `snapchat-profiles-list` | | `POST /v1/connect/bluesky/credentials` | `POST /connect/bluesky/credentials` | `connect-bluesky-credentials` | | `POST /v1/connect/openai-ads/credentials` | `POST /connect/openai-ads/credentials` | `connect-openai-ads` | | `POST /v1/connect/whop-ads/credentials` | `POST /connect/whop-ads/credentials` | `connect-whop-ads` | | `POST /v1/connect/discord` | `POST /connect/discord` | `connect-discord-channels` | | `GET /v1/accounts/{accountId}/webhook-subscription` | `GET /accounts/{accountId}/webhook-subscription`
`GET /accounts/{accountId}/facebook/webhook-subscription` | `get-facebook-webhook-subscription` `facebook-webhook-subscription-get` | | `POST /v1/accounts/{accountId}/webhook-subscription` | `POST /accounts/{accountId}/webhook-subscription`
`POST /accounts/{accountId}/facebook/webhook-subscription/subscribe` | `resubscribe-facebook-webhooks` `facebook-webhook-subscription-subscribe` | | `GET /v1/accounts/{accountId}/facebook-page` | `GET /accounts/{accountId}/facebook-page`
`GET /accounts/{accountId}/facebook/pages` | `list-facebook-pages` `facebook-pages-list` | | `PUT /v1/accounts/{accountId}/facebook-page` | `PATCH /accounts/{accountId}/facebook-page`
`POST /accounts/{accountId}/facebook/pages/{itemId}/select` | `select-facebook-page` `facebook-pages-select` | | `GET /v1/accounts/{accountId}/linkedin-organizations` | `GET /accounts/{accountId}/linkedin-organizations`
`GET /accounts/{accountId}/linkedin/organizations` | `list-linkedin-organizations` `linkedin-organizations-list` | | `PUT /v1/accounts/{accountId}/linkedin-organization` | `PATCH /accounts/{accountId}/linkedin-organization`
`POST /accounts/{accountId}/linkedin/organizations/{itemId}/switch-to-organization` | `switch-linkedin-account-type` `linkedin-organizations-switch-to-organization` | | `GET /v1/accounts/{accountId}/pinterest-boards` | `GET /accounts/{accountId}/pinterest-boards`
`GET /accounts/{accountId}/pinterest/boards` | `list-pinterest-boards` `pinterest-boards-list` | | `POST /v1/accounts/{accountId}/pinterest-boards` | `POST /accounts/{accountId}/pinterest-boards`
`POST /accounts/{accountId}/pinterest/boards` | `create-pinterest-board` `pinterest-boards-create` | | `PUT /v1/accounts/{accountId}/pinterest-boards` | `PATCH /accounts/{accountId}/pinterest-boards`
`PATCH /accounts/{accountId}/pinterest/boards/{itemId}` | `set-default-pinterest-board` `pinterest-boards-update` | | `GET /v1/accounts/{accountId}/youtube-captions` | `GET /accounts/{accountId}/youtube-captions`
`GET /accounts/{accountId}/youtube/captions` | `get-youtube-transcript` `youtube-captions-list` | | `GET /v1/accounts/{accountId}/youtube-playlists` | `GET /accounts/{accountId}/youtube-playlists`
`GET /accounts/{accountId}/youtube/playlists` | `list-youtube-playlists` `youtube-playlists-list` | | `POST /v1/accounts/{accountId}/youtube-playlists` | `POST /accounts/{accountId}/youtube-playlists`
`POST /accounts/{accountId}/youtube/playlists` | `create-youtube-playlist` `youtube-playlists-create` | | `PUT /v1/accounts/{accountId}/youtube-playlists` | `PATCH /accounts/{accountId}/youtube-playlists`
`PATCH /accounts/{accountId}/youtube/playlists/{itemId}` | `set-default-youtube-playlist` `youtube-playlists-update` | | `GET /v1/accounts/{accountId}/gmb-locations` | `GET /accounts/{accountId}/gmb-locations`
`GET /accounts/{accountId}/google-business/locations` | `list-gmb-locations` `google-business-locations-list` | | `PUT /v1/accounts/{accountId}/gmb-locations` | `PATCH /accounts/{accountId}/gmb-locations`
`POST /accounts/{accountId}/google-business/locations/{itemId}/select` | `select-gmb-location` `google-business-locations-select` | | `POST /v1/accounts/{accountId}/gmb-locations/assign` | `POST /accounts/{accountId}/gmb-locations/assign`
`POST /accounts/{accountId}/google-business/locations` | `assign-gmb-location` `google-business-locations-create` | | `GET /v1/accounts/{accountId}/reddit-subreddits` | `GET /accounts/{accountId}/reddit-subreddits`
`GET /accounts/{accountId}/reddit/my-subreddits` | `list-reddit-subreddits` `reddit-my-subreddits-list` | | `PUT /v1/accounts/{accountId}/reddit-subreddits` | `PATCH /accounts/{accountId}/reddit-subreddits`
`POST /accounts/{accountId}/reddit/my-subreddits/{itemId}/set-default` | `set-default-reddit-subreddit` `reddit-my-subreddits-set-default` | | `GET /v1/accounts/{accountId}/reddit-subreddits/{subreddit}/rules` | `GET /accounts/{accountId}/reddit-subreddits/{subreddit}/rules`
`GET /accounts/{accountId}/reddit/subreddit-rules` | `get-reddit-subreddit-rules` `reddit-subreddit-rules-list` | | `POST /v1/accounts/{accountId}/reddit-vote` | `POST /accounts/{accountId}/reddit-vote`
`POST /accounts/{accountId}/reddit/feed/{itemId}/vote` | `vote-on-reddit` `reddit-feed-vote` | | `GET /v1/accounts/{accountId}/reddit-flairs` | `GET /accounts/{accountId}/reddit-flairs`
`GET /accounts/{accountId}/reddit/post-flairs` | `list-reddit-flairs` `reddit-post-flairs-list` | | `POST /v1/accounts/{accountId}/reddit-flairs` | `POST /accounts/{accountId}/reddit-flairs`
`POST /accounts/{accountId}/reddit/my-posts`
`POST /accounts/{accountId}/reddit/post-flairs/{itemId}/apply` | `set-reddit-post-flair` `reddit-my-posts-create` `reddit-post-flairs-apply` | ### GMB Reviews | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/gmb-reviews` | `GET /accounts/{accountId}/gmb-reviews`
`GET /accounts/{accountId}/google-business/reviews` | `list-gmb-reviews` `google-business-reviews-list` | | `POST /v1/accounts/{accountId}/gmb-reviews/batch` | `POST /accounts/{accountId}/gmb-reviews/batch`
`POST /accounts/{accountId}/google-business/reviews/{itemId}/reply` | `batch-get-gmb-reviews` `google-business-reviews-reply` | | `GET /v1/accounts/{accountId}/gmb-reviews/{reviewId}` | `GET /accounts/{accountId}/gmb-reviews/{reviewId}`
`GET /accounts/{accountId}/google-business/reviews/{itemId}` | `get-gmb-review` `google-business-reviews-get` | | `POST /v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply` | `POST /accounts/{accountId}/gmb-reviews/{reviewId}/reply`
`POST /accounts/{accountId}/google-business/reviews/{itemId}/reply` | `reply-to-gmb-review` `google-business-reviews-reply` | | `DELETE /v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply` | `DELETE /accounts/{accountId}/gmb-reviews/{reviewId}/reply`
`POST /accounts/{accountId}/google-business/reviews/{itemId}/reply` | `delete-gmb-review-reply` `google-business-reviews-reply` | ### GMB Verifications | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/gmb-verifications` | `GET /accounts/{accountId}/gmb-verifications`
`GET /accounts/{accountId}/google-business/verifications`
`GET /accounts/{accountId}/google-business/voice-of-merchant` | `get-gmb-verifications` `google-business-verifications-list` `google-business-voice-of-merchant-get` | | `POST /v1/accounts/{accountId}/gmb-verifications` | `POST /accounts/{accountId}/gmb-verifications`
`POST /accounts/{accountId}/google-business/verifications` | `start-gmb-verification` `google-business-verifications-create` | | `POST /v1/accounts/{accountId}/gmb-verifications/options` | `POST /accounts/{accountId}/gmb-verifications/options`
`POST /accounts/{accountId}/google-business/verifications` | `fetch-gmb-verification-options` `google-business-verifications-create` | | `POST /v1/accounts/{accountId}/gmb-verifications/{verificationId}/complete` | `POST /accounts/{accountId}/gmb-verifications/{verificationId}/complete`
`POST /accounts/{accountId}/google-business/verifications` | `complete-gmb-verification` `google-business-verifications-create` | ### GMB Food Menus | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/gmb-food-menus` | `GET /accounts/{accountId}/gmb-food-menus`
`GET /accounts/{accountId}/google-business/food-menus` | `get-gmb-food-menus` `google-business-food-menus-get` | | `PUT /v1/accounts/{accountId}/gmb-food-menus` | `PATCH /accounts/{accountId}/gmb-food-menus`
`PATCH /accounts/{accountId}/google-business/food-menus` | `update-gmb-food-menus` `google-business-food-menus-update` | ### GMB Location Details | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/gmb-location-details` | `GET /accounts/{accountId}/gmb-location-details`
`GET /accounts/{accountId}/google-business/business-info`
`GET /accounts/{accountId}/google-business/hours` | `get-gmb-location-details` `google-business-business-info-get` `google-business-hours-get` | | `PUT /v1/accounts/{accountId}/gmb-location-details` | `PATCH /accounts/{accountId}/gmb-location-details`
`PATCH /accounts/{accountId}/google-business/business-info`
`PATCH /accounts/{accountId}/google-business/hours` | `update-gmb-location-details` `google-business-business-info-update` `google-business-hours-update` | ### GMB Media | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/gmb-media` | `GET /accounts/{accountId}/gmb-media`
`GET /accounts/{accountId}/google-business/media` | `list-gmb-media` `google-business-media-list` | | `POST /v1/accounts/{accountId}/gmb-media` | `POST /accounts/{accountId}/gmb-media`
`POST /accounts/{accountId}/google-business/media` | `upload-gmb-media` `google-business-media-create` | | `DELETE /v1/accounts/{accountId}/gmb-media` | `DELETE /accounts/{accountId}/gmb-media`
`DELETE /accounts/{accountId}/google-business/media/{itemId}` | `delete-gmb-media` `google-business-media-delete` | ### GMB Attributes | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/gmb-attribute-metadata` | `GET /accounts/{accountId}/gmb-attribute-metadata`
`GET /accounts/{accountId}/google-business/attributes`
`GET /accounts/{accountId}/google-business/attribute-metadata` | `get-gmb-attribute-metadata` `google-business-attributes-list` `google-business-attribute-metadata-list` | | `GET /v1/accounts/{accountId}/gmb-attributes` | `GET /accounts/{accountId}/gmb-attributes`
`GET /accounts/{accountId}/google-business/attributes` | `get-gmb-attributes` `google-business-attributes-list` | | `PUT /v1/accounts/{accountId}/gmb-attributes` | `PATCH /accounts/{accountId}/gmb-attributes`
`PATCH /accounts/{accountId}/google-business/attributes/{itemId}` | `update-gmb-attributes` `google-business-attributes-update` | ### GMB Place Actions | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/gmb-place-actions` | `GET /accounts/{accountId}/gmb-place-actions`
`GET /accounts/{accountId}/google-business/place-action-links` | `list-gmb-place-actions` `google-business-place-action-links-list` | | `POST /v1/accounts/{accountId}/gmb-place-actions` | `POST /accounts/{accountId}/gmb-place-actions`
`POST /accounts/{accountId}/google-business/place-action-links` | `create-gmb-place-action` `google-business-place-action-links-create` | | `PATCH /v1/accounts/{accountId}/gmb-place-actions` | `PATCH /accounts/{accountId}/gmb-place-actions`
`PATCH /accounts/{accountId}/google-business/place-action-links/{itemId}` | `update-gmb-place-action` `google-business-place-action-links-update` | | `DELETE /v1/accounts/{accountId}/gmb-place-actions` | `DELETE /accounts/{accountId}/gmb-place-actions`
`DELETE /accounts/{accountId}/google-business/place-action-links/{itemId}` | `delete-gmb-place-action` `google-business-place-action-links-delete` | ### GMB Services | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/gmb-services` | `GET /accounts/{accountId}/gmb-services`
`GET /accounts/{accountId}/google-business/services` | `get-gmb-services` `google-business-services-list` | | `PUT /v1/accounts/{accountId}/gmb-services` | `PATCH /accounts/{accountId}/gmb-services`
`PATCH /accounts/{accountId}/google-business/services/{itemId}` | `replace-gmb-services` `google-business-services-update` | ### LinkedIn Mentions | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/linkedin-mentions` | `GET /accounts/{accountId}/linkedin-mentions`
`GET /accounts/{accountId}/linkedin/mention-search` | `resolve-linkedin-mention` `linkedin-mention-search-list` | ### Instagram | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/instagram/stories` | `GET /accounts/{accountId}/instagram/stories` | `list-instagram-stories` | | `GET /v1/accounts/{accountId}/instagram/publishing-limit` | `GET /accounts/{accountId}/instagram/publishing-limit` | `get-instagram-publishing-limit` | | `GET /v1/accounts/{accountId}/instagram/audio` | `GET /accounts/{accountId}/instagram/audio` | `search-instagram-audio` | | `GET /v1/accounts/{accountId}/instagram/audio/{audioId}` | `GET /accounts/{accountId}/instagram/audio/{audioId}` | `get-instagram-audio` | | `GET /v1/accounts/{accountId}/instagram/business-discovery` | `GET /accounts/{accountId}/instagram/business-discovery`
`GET /accounts/{accountId}/instagram/business-discovery/{itemId}` | `instagram-business-discovery` `instagram-business-discovery-get` | | `GET /v1/accounts/{accountId}/instagram/stories/{storyId}/insights` | `GET /accounts/{accountId}/instagram/stories/{storyId}/insights` | `get-instagram-story-insights` | ### Discord | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/discord-settings` | `GET /accounts/{accountId}/discord-settings`
`GET /accounts/{accountId}/discord/settings` | `get-discord-settings` `discord-settings-get` | | `PATCH /v1/accounts/{accountId}/discord-settings` | `PATCH /accounts/{accountId}/discord-settings`
`PATCH /accounts/{accountId}/discord/settings` | `update-discord-settings` `discord-settings-update` | | `GET /v1/accounts/{accountId}/discord-channels` | `GET /accounts/{accountId}/discord-channels`
`GET /accounts/{accountId}/discord/channels` | `list-discord-channels` `discord-channels-list` | | `POST /v1/discord/dms` | `POST /discord/dms`
`POST /accounts/{accountId}/discord/direct-messages` | `send-discord-dm` `discord-direct-messages-create` | | `GET /v1/discord/guilds/{guildId}/roles` | `GET /discord/guilds/{guildId}/roles`
`GET /accounts/{accountId}/discord/roles` | `list-discord-roles` `discord-roles-list` | | `POST /v1/discord/guilds/{guildId}/roles` | `POST /discord/guilds/{guildId}/roles`
`POST /accounts/{accountId}/discord/roles` | `create-discord-role` `discord-roles-create` | | `PATCH /v1/discord/guilds/{guildId}/roles/{roleId}` | `PATCH /discord/guilds/{guildId}/roles/{roleId}`
`PATCH /accounts/{accountId}/discord/roles/{itemId}` | `update-discord-role` `discord-roles-update` | | `DELETE /v1/discord/guilds/{guildId}/roles/{roleId}` | `DELETE /discord/guilds/{guildId}/roles/{roleId}`
`DELETE /accounts/{accountId}/discord/roles/{itemId}` | `delete-discord-role` `discord-roles-delete` | | `GET /v1/discord/guilds/{guildId}/members` | `GET /discord/guilds/{guildId}/members`
`GET /accounts/{accountId}/discord/members` | `list-discord-members` `discord-members-list` | | `GET /v1/discord/guilds/{guildId}/members/search` | `GET /discord/guilds/{guildId}/members/search`
`GET /accounts/{accountId}/discord/members` | `search-discord-members` `discord-members-list` | | `GET /v1/discord/guilds/{guildId}/members/{userId}` | `GET /discord/guilds/{guildId}/members/{userId}`
`GET /accounts/{accountId}/discord/members/{itemId}` | `get-discord-member` `discord-members-get` | | `PUT /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}` | `PUT /discord/guilds/{guildId}/members/{userId}/roles/{roleId}`
`PATCH /accounts/{accountId}/discord/members/{itemId}` | `add-discord-member-role` `discord-members-update` | | `DELETE /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}` | `DELETE /discord/guilds/{guildId}/members/{userId}/roles/{roleId}`
`DELETE /accounts/{accountId}/discord/members/{itemId}` | `remove-discord-member-role` `discord-members-delete` | | `DELETE /v1/discord/channels/{channelId}/messages/{messageId}` | `DELETE /discord/channels/{channelId}/messages/{messageId}`
`DELETE /accounts/{accountId}/discord/messages/{itemId}` | `delete-discord-message` `discord-messages-delete` | | `POST /v1/discord/channels/{channelId}/messages/{messageId}/crosspost` | `POST /discord/channels/{channelId}/messages/{messageId}/crosspost`
`POST /accounts/{accountId}/discord/messages` | `crosspost-discord-message` `discord-messages-create` | | `POST /v1/discord/channels/{channelId}/threads` | `POST /discord/channels/{channelId}/threads`
`POST /accounts/{accountId}/discord/threads` | `create-discord-thread` `discord-threads-create` | | `GET /v1/discord/channels/{channelId}/pins` | `GET /discord/channels/{channelId}/pins`
`GET /accounts/{accountId}/discord/pins` | `list-discord-pins` `discord-pins-list` | | `PUT /v1/discord/channels/{channelId}/pins/{messageId}` | `PUT /discord/channels/{channelId}/pins/{messageId}`
`POST /accounts/{accountId}/discord/pins` | `pin-discord-message` `discord-pins-create` | | `DELETE /v1/discord/channels/{channelId}/pins/{messageId}` | `DELETE /discord/channels/{channelId}/pins/{messageId}`
`DELETE /accounts/{accountId}/discord/pins/{itemId}` | `unpin-discord-message` `discord-pins-delete` | | `GET /v1/discord/guilds/{guildId}/events` | `GET /discord/guilds/{guildId}/events`
`GET /accounts/{accountId}/discord/scheduled-events` | `list-discord-events` `discord-scheduled-events-list` | | `POST /v1/discord/guilds/{guildId}/events` | `POST /discord/guilds/{guildId}/events`
`POST /accounts/{accountId}/discord/scheduled-events` | `create-discord-event` `discord-scheduled-events-create` | | `GET /v1/discord/guilds/{guildId}/events/{eventId}` | `GET /discord/guilds/{guildId}/events/{eventId}`
`GET /accounts/{accountId}/discord/scheduled-events/{itemId}` | `get-discord-event` `discord-scheduled-events-get` | | `PATCH /v1/discord/guilds/{guildId}/events/{eventId}` | `PATCH /discord/guilds/{guildId}/events/{eventId}`
`PATCH /accounts/{accountId}/discord/scheduled-events/{itemId}` | `update-discord-event` `discord-scheduled-events-update` | | `DELETE /v1/discord/guilds/{guildId}/events/{eventId}` | `DELETE /discord/guilds/{guildId}/events/{eventId}`
`DELETE /accounts/{accountId}/discord/scheduled-events/{itemId}` | `delete-discord-event` `discord-scheduled-events-delete` | ### Queue | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/queue/slots` | `GET /queues` | `list-queues` | | `POST /v1/queue/slots` | `POST /queues` | `create-queue` | | `PUT /v1/queue/slots` | `PATCH /queues/{id}` | `update-queue` | | `DELETE /v1/queue/slots` | `DELETE /queues/{id}` | `delete-queue` | | `GET /v1/queue/preview` | `GET /queues/preview` | `preview-queue` | | `GET /v1/queue/next-slot` | `GET /queues/next-slot` | `get-next-queue-slot` | ### Webhooks | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/webhooks/settings` | `GET /webhooks` | `list-webhooks` | | `POST /v1/webhooks/settings` | `POST /webhooks` | `create-webhook` | | `PUT /v1/webhooks/settings` | `PATCH /webhooks/{id}` | `update-webhook` | | `DELETE /v1/webhooks/settings` | `DELETE /webhooks/{id}` | `delete-webhook` | | `GET /v1/webhooks/logs` | `GET /webhooks/deliveries` | `list-all-webhook-deliveries` | | `POST /v1/webhooks/logs/redeliver` | `POST /webhooks/deliveries/{id}/redeliver` | `redeliver-webhook-delivery` | | `POST /v1/webhooks/test` | `POST /webhooks/{id}/test` | `test-webhook` | ### Logs | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/logs` | `GET /logs` | `list-request-logs` | ### Messages | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/inbox/conversations` | `GET /inbox/conversations`
`GET /accounts/{accountId}/bluesky/conversations`
`GET /accounts/{accountId}/facebook/conversations`
`GET /accounts/{accountId}/instagram/conversations`
`GET /accounts/{accountId}/reddit/messages`
`GET /accounts/{accountId}/tiktok/conversations`
`GET /accounts/{accountId}/x/conversations` | `list-conversations` `bluesky-conversations-list` `facebook-conversations-list` `instagram-conversations-list` `reddit-messages-list` `tiktok-conversations-list` `x-conversations-list` | | `POST /v1/inbox/conversations` | `POST /inbox/conversations`
`POST /accounts/{accountId}/bluesky/conversations`
`POST /accounts/{accountId}/reddit/messages`
`POST /accounts/{accountId}/x/conversations` | `create-conversation` `bluesky-conversations-create` `reddit-messages-create` `x-conversations-create` | | `GET /v1/inbox/conversations/search` | `GET /inbox/conversations/search` | `search-conversations` | | `GET /v1/inbox/conversations/{conversationId}` | `GET /inbox/conversations/{conversationId}`
`GET /accounts/{accountId}/bluesky/conversations/{itemId}`
`GET /accounts/{accountId}/facebook/conversations/{itemId}`
`GET /accounts/{accountId}/instagram/conversations/{itemId}`
`GET /accounts/{accountId}/reddit/messages/{itemId}`
`GET /accounts/{accountId}/tiktok/conversations/{itemId}`
`GET /accounts/{accountId}/x/conversations/{itemId}` | `get-conversation` `bluesky-conversations-get` `facebook-conversations-get` `instagram-conversations-get` `reddit-messages-get` `tiktok-conversations-get` `x-conversations-get` | | `PUT /v1/inbox/conversations/{conversationId}` | `PATCH /inbox/conversations/{conversationId}` | `update-conversation` | | `GET /v1/inbox/conversations/{conversationId}/messages` | `GET /inbox/conversations/{conversationId}/messages`
`GET /accounts/{accountId}/bluesky/messages`
`GET /accounts/{accountId}/facebook/conversations`
`GET /accounts/{accountId}/instagram/conversations`
`GET /accounts/{accountId}/reddit/messages`
`GET /accounts/{accountId}/tiktok/messages`
`GET /accounts/{accountId}/x/conversations` | `list-messages` `bluesky-messages-list` `facebook-conversations-list` `instagram-conversations-list` `reddit-messages-list` `tiktok-messages-list` `x-conversations-list` | | `POST /v1/inbox/conversations/{conversationId}/messages` | `POST /inbox/conversations/{conversationId}/messages`
`POST /accounts/{accountId}/bluesky/messages`
`POST /accounts/{accountId}/facebook/conversations/{itemId}/messages`
`POST /accounts/{accountId}/instagram/conversations/{itemId}/send`
`POST /accounts/{accountId}/reddit/messages`
`POST /accounts/{accountId}/tiktok/messages`
`POST /accounts/{accountId}/x/conversations` | `send-message` `bluesky-messages-create` `facebook-conversations-messages` `instagram-conversations-send` `reddit-messages-create` `tiktok-messages-create` `x-conversations-create` | | `DELETE /v1/inbox/conversations/{conversationId}/messages/{messageId}` | `DELETE /inbox/conversations/{conversationId}/messages/{messageId}`
`DELETE /accounts/{accountId}/bluesky/messages/{itemId}`
`DELETE /accounts/{accountId}/reddit/messages/{itemId}`
`POST /accounts/{accountId}/x/conversations/{itemId}/send` | `delete-message` `bluesky-messages-delete` `reddit-messages-delete` `x-conversations-send` | | `POST /v1/inbox/conversations/{conversationId}/typing` | `POST /inbox/conversations/{conversationId}/typing`
`POST /accounts/{accountId}/facebook/conversations/{itemId}/messages`
`POST /accounts/{accountId}/instagram/conversations/{itemId}/send`
`POST /accounts/{accountId}/tiktok/conversations/{itemId}/typing` | `send-typing-indicator` `facebook-conversations-messages` `instagram-conversations-send` `tiktok-conversations-typing` | | `POST /v1/inbox/conversations/{conversationId}/thread-control` | `POST /inbox/conversations/{conversationId}/thread-control`
`POST /accounts/{accountId}/facebook/conversations/{itemId}/messages` | `change-thread-control` `facebook-conversations-messages` | | `POST /v1/inbox/conversations/{conversationId}/accept` | `POST /inbox/conversations/{conversationId}/accept`
`POST /accounts/{accountId}/bluesky/conversations`
`POST /accounts/{accountId}/facebook/conversations/{itemId}/messages` | `accept-conversation` `bluesky-conversations-create` `facebook-conversations-messages` | | `POST /v1/inbox/conversations/{conversationId}/read` | `POST /inbox/conversations/{conversationId}/read`
`POST /accounts/{accountId}/bluesky/conversations`
`POST /accounts/{accountId}/facebook/conversations/{itemId}/messages`
`POST /accounts/{accountId}/instagram/conversations/{itemId}/send`
`POST /accounts/{accountId}/reddit/messages`
`POST /accounts/{accountId}/tiktok/conversations/{itemId}/typing` | `mark-conversation-read` `bluesky-conversations-create` `facebook-conversations-messages` `instagram-conversations-send` `reddit-messages-create` `tiktok-conversations-typing` | | `POST /v1/inbox/conversations/{conversationId}/messages/{messageId}/reactions` | `POST /inbox/conversations/{conversationId}/messages/{messageId}/reactions`
`POST /accounts/{accountId}/bluesky/messages`
`POST /accounts/{accountId}/facebook/conversations/{itemId}/messages`
`POST /accounts/{accountId}/instagram/conversations/{itemId}/send` | `add-message-reaction` `bluesky-messages-create` `facebook-conversations-messages` `instagram-conversations-send` | | `DELETE /v1/inbox/conversations/{conversationId}/messages/{messageId}/reactions` | `DELETE /inbox/conversations/{conversationId}/messages/{messageId}/reactions`
`DELETE /accounts/{accountId}/bluesky/messages/{itemId}`
`POST /accounts/{accountId}/facebook/conversations/{itemId}/messages`
`POST /accounts/{accountId}/instagram/conversations/{itemId}/send` | `remove-message-reaction` `bluesky-messages-delete` `facebook-conversations-messages` `instagram-conversations-send` | | `POST /v1/media/upload-direct` | `POST /media/upload-direct` | | | `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}` | `GET /inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}`
`GET /accounts/{accountId}/x/conversations/{itemId}` | `get-message-attachment` `x-conversations-get` | ### Account Settings | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/accounts/{accountId}/messenger-menu` | `GET /accounts/{accountId}/messenger-menu`
`GET /accounts/{accountId}/facebook/messenger-menu`
`GET /accounts/{accountId}/instagram/persistent-menu` | `get-messenger-menu` `facebook-messenger-menu-get` `instagram-persistent-menu-get` | | `PUT /v1/accounts/{accountId}/messenger-menu` | `PATCH /accounts/{accountId}/messenger-menu`
`PATCH /accounts/{accountId}/facebook/messenger-menu`
`PATCH /accounts/{accountId}/instagram/persistent-menu` | `set-messenger-menu` `facebook-messenger-menu-update` `instagram-persistent-menu-update` | | `DELETE /v1/accounts/{accountId}/messenger-menu` | `DELETE /accounts/{accountId}/messenger-menu`
`DELETE /accounts/{accountId}/facebook/messenger-menu`
`DELETE /accounts/{accountId}/instagram/persistent-menu` | `delete-messenger-menu` `facebook-messenger-menu-delete` `instagram-persistent-menu-delete` | | `GET /v1/accounts/{accountId}/messenger-get-started` | `GET /accounts/{accountId}/messenger-get-started`
`GET /accounts/{accountId}/facebook/messenger-get-started` | `get-messenger-get-started` `facebook-messenger-get-started-get` | | `PUT /v1/accounts/{accountId}/messenger-get-started` | `PATCH /accounts/{accountId}/messenger-get-started`
`PATCH /accounts/{accountId}/facebook/messenger-get-started` | `set-messenger-get-started` `facebook-messenger-get-started-update` | | `DELETE /v1/accounts/{accountId}/messenger-get-started` | `DELETE /accounts/{accountId}/messenger-get-started`
`DELETE /accounts/{accountId}/facebook/messenger-get-started` | `delete-messenger-get-started` `facebook-messenger-get-started-delete` | | `GET /v1/accounts/{accountId}/messenger-greeting` | `GET /accounts/{accountId}/messenger-greeting`
`GET /accounts/{accountId}/facebook/messenger-greeting` | `get-messenger-greeting` `facebook-messenger-greeting-get` | | `PUT /v1/accounts/{accountId}/messenger-greeting` | `PATCH /accounts/{accountId}/messenger-greeting`
`PATCH /accounts/{accountId}/facebook/messenger-greeting` | `set-messenger-greeting` `facebook-messenger-greeting-update` | | `DELETE /v1/accounts/{accountId}/messenger-greeting` | `DELETE /accounts/{accountId}/messenger-greeting`
`DELETE /accounts/{accountId}/facebook/messenger-greeting` | `delete-messenger-greeting` `facebook-messenger-greeting-delete` | | `GET /v1/accounts/{accountId}/messenger-ice-breakers` | `GET /accounts/{accountId}/messenger-ice-breakers`
`GET /accounts/{accountId}/facebook/messenger-ice-breakers` | `get-messenger-ice-breakers` `facebook-messenger-ice-breakers-get` | | `PUT /v1/accounts/{accountId}/messenger-ice-breakers` | `PATCH /accounts/{accountId}/messenger-ice-breakers`
`PATCH /accounts/{accountId}/facebook/messenger-ice-breakers` | `set-messenger-ice-breakers` `facebook-messenger-ice-breakers-update` | | `DELETE /v1/accounts/{accountId}/messenger-ice-breakers` | `DELETE /accounts/{accountId}/messenger-ice-breakers`
`DELETE /accounts/{accountId}/facebook/messenger-ice-breakers` | `delete-messenger-ice-breakers` `facebook-messenger-ice-breakers-delete` | | `GET /v1/accounts/{accountId}/instagram-ice-breakers` | `GET /accounts/{accountId}/instagram-ice-breakers`
`GET /accounts/{accountId}/instagram/ice-breakers` | `get-instagram-ice-breakers` `instagram-ice-breakers-get` | | `PUT /v1/accounts/{accountId}/instagram-ice-breakers` | `PATCH /accounts/{accountId}/instagram-ice-breakers`
`PATCH /accounts/{accountId}/instagram/ice-breakers` | `set-instagram-ice-breakers` `instagram-ice-breakers-update` | | `DELETE /v1/accounts/{accountId}/instagram-ice-breakers` | `DELETE /accounts/{accountId}/instagram-ice-breakers`
`DELETE /accounts/{accountId}/instagram/ice-breakers` | `delete-instagram-ice-breakers` `instagram-ice-breakers-delete` | ### Comments | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/inbox/comments` | `GET /inbox/posts`
`GET /accounts/{accountId}/facebook/commented-posts`
`GET /accounts/{accountId}/instagram/comments`
`GET /accounts/{accountId}/linkedin/comments`
`GET /accounts/{accountId}/reddit/my-posts`
`GET /accounts/{accountId}/threads/commented-posts`
`GET /accounts/{accountId}/tiktok/comments`
`GET /accounts/{accountId}/x/replies`
`GET /accounts/{accountId}/youtube/comments` | `list-inbox-posts` `facebook-commented-posts-list` `instagram-comments-list` `linkedin-comments-list` `reddit-my-posts-list` `threads-commented-posts-list` `tiktok-comments-list` `x-replies-list` `youtube-comments-list` | | `GET /v1/inbox/comments/{postId}` | `GET /inbox/posts/{postId}/comments`
`GET /accounts/{accountId}/bluesky/replies`
`GET /accounts/{accountId}/facebook/comments/{itemId}`
`GET /accounts/{accountId}/instagram/comments/{itemId}`
`GET /accounts/{accountId}/linkedin/comments/{itemId}`
`GET /accounts/{accountId}/reddit/post-comments`
`GET /accounts/{accountId}/threads/replies`
`GET /accounts/{accountId}/tiktok/comments`
`GET /accounts/{accountId}/x/replies`
`GET /accounts/{accountId}/youtube/comments/{itemId}` | `list-post-comments` `bluesky-replies-list` `facebook-comments-get` `instagram-comments-get` `linkedin-comments-get` `reddit-post-comments-list` `threads-replies-list` `tiktok-comments-list` `x-replies-list` `youtube-comments-get` | | `POST /v1/inbox/comments/{postId}` | `POST /inbox/posts/{postId}/comments`
`POST /accounts/{accountId}/bluesky/replies`
`POST /accounts/{accountId}/facebook/comments`
`POST /accounts/{accountId}/instagram/comments`
`POST /accounts/{accountId}/linkedin/comments`
`POST /accounts/{accountId}/reddit/post-comments`
`POST /accounts/{accountId}/threads/replies`
`POST /accounts/{accountId}/tiktok/comments`
`POST /accounts/{accountId}/x/replies`
`POST /accounts/{accountId}/youtube/comments` | `create-comment` `bluesky-replies-create` `facebook-comments-create` `instagram-comments-create` `linkedin-comments-create` `reddit-post-comments-create` `threads-replies-create` `tiktok-comments-create` `x-replies-create` `youtube-comments-create` | | `DELETE /v1/inbox/comments/{postId}` | `DELETE /inbox/comments/{commentId}`
`DELETE /accounts/{accountId}/bluesky/replies/{itemId}`
`DELETE /accounts/{accountId}/facebook/comments/{itemId}`
`DELETE /accounts/{accountId}/instagram/comments/{itemId}`
`DELETE /accounts/{accountId}/linkedin/comments/{itemId}`
`DELETE /accounts/{accountId}/reddit/post-comments/{itemId}`
`DELETE /accounts/{accountId}/threads/replies/{itemId}`
`DELETE /accounts/{accountId}/tiktok/comments/{itemId}`
`DELETE /accounts/{accountId}/x/replies/{itemId}`
`DELETE /accounts/{accountId}/youtube/comments/{itemId}` | `delete-comment` `bluesky-replies-delete` `facebook-comments-delete` `instagram-comments-delete` `linkedin-comments-delete` `reddit-post-comments-delete` `threads-replies-delete` `tiktok-comments-delete` `x-replies-delete` `youtube-comments-delete` | | `PATCH /v1/inbox/comments/{postId}/{commentId}` | `PATCH /inbox/comments/{commentId}`
`PATCH /accounts/{accountId}/linkedin/comments/{itemId}`
`PATCH /accounts/{accountId}/reddit/post-comments/{itemId}` | `update-comment` `linkedin-comments-update` `reddit-post-comments-update` | | `POST /v1/inbox/comments/{postId}/{commentId}/moderation` | `POST /inbox/comments/{commentId}/moderation`
`POST /accounts/{accountId}/youtube/comments`
`POST /accounts/{accountId}/youtube/held-for-review/{itemId}/reply` | `set-comment-moderation` `youtube-comments-create` `youtube-held-for-review-reply` | | `POST /v1/inbox/comments/{postId}/{commentId}/hide` | `POST /inbox/comments/{commentId}/hide`
`POST /accounts/{accountId}/bluesky/replies`
`POST /accounts/{accountId}/facebook/comments`
`POST /accounts/{accountId}/instagram/comments`
`POST /accounts/{accountId}/threads/replies`
`POST /accounts/{accountId}/tiktok/comments`
`POST /accounts/{accountId}/x/replies` | `hide-comment` `bluesky-replies-create` `facebook-comments-create` `instagram-comments-create` `threads-replies-create` `tiktok-comments-create` `x-replies-create` | | `DELETE /v1/inbox/comments/{postId}/{commentId}/hide` | `DELETE /inbox/comments/{commentId}/hide`
`DELETE /accounts/{accountId}/bluesky/replies/{itemId}`
`DELETE /accounts/{accountId}/facebook/comments/{itemId}`
`DELETE /accounts/{accountId}/instagram/comments/{itemId}`
`DELETE /accounts/{accountId}/threads/replies/{itemId}`
`DELETE /accounts/{accountId}/tiktok/comments/{itemId}`
`DELETE /accounts/{accountId}/x/replies/{itemId}` | `unhide-comment` `bluesky-replies-delete` `facebook-comments-delete` `instagram-comments-delete` `threads-replies-delete` `tiktok-comments-delete` `x-replies-delete` | | `POST /v1/inbox/comments/{postId}/{commentId}/pin` | `POST /inbox/comments/{commentId}/pin`
`POST /accounts/{accountId}/reddit/post-comments` | `pin-comment` `reddit-post-comments-create` | | `DELETE /v1/inbox/comments/{postId}/{commentId}/pin` | `DELETE /inbox/comments/{commentId}/pin`
`DELETE /accounts/{accountId}/reddit/post-comments/{itemId}` | `unpin-comment` `reddit-post-comments-delete` | | `POST /v1/inbox/comments/{postId}/{commentId}/like` | `POST /inbox/comments/{commentId}/like`
`POST /accounts/{accountId}/bluesky/replies`
`POST /accounts/{accountId}/facebook/comments`
`POST /accounts/{accountId}/instagram/comments`
`POST /accounts/{accountId}/linkedin/comments`
`POST /accounts/{accountId}/reddit/post-comments`
`POST /accounts/{accountId}/tiktok/comments`
`POST /accounts/{accountId}/x/replies` | `like-comment` `bluesky-replies-create` `facebook-comments-create` `instagram-comments-create` `linkedin-comments-create` `reddit-post-comments-create` `tiktok-comments-create` `x-replies-create` | | `DELETE /v1/inbox/comments/{postId}/{commentId}/like` | `DELETE /inbox/comments/{commentId}/like`
`DELETE /accounts/{accountId}/bluesky/replies/{itemId}`
`DELETE /accounts/{accountId}/facebook/comments/{itemId}`
`DELETE /accounts/{accountId}/instagram/comments/{itemId}`
`DELETE /accounts/{accountId}/linkedin/comments/{itemId}`
`DELETE /accounts/{accountId}/reddit/post-comments/{itemId}`
`DELETE /accounts/{accountId}/tiktok/comments/{itemId}`
`DELETE /accounts/{accountId}/x/replies/{itemId}` | `unlike-comment` `bluesky-replies-delete` `facebook-comments-delete` `instagram-comments-delete` `linkedin-comments-delete` `reddit-post-comments-delete` `tiktok-comments-delete` `x-replies-delete` | | `POST /v1/inbox/posts/{postId}/like` | `POST /inbox/posts/{postId}/like`
`POST /accounts/{accountId}/bluesky/posts`
`POST /accounts/{accountId}/facebook/posts`
`POST /accounts/{accountId}/instagram/mentions/{itemId}/reply`
`POST /accounts/{accountId}/linkedin/reactions`
`POST /accounts/{accountId}/x/posts`
`POST /accounts/{accountId}/x/liked-posts`
`POST /accounts/{accountId}/youtube/videos` | `like-post` `bluesky-posts-create` `facebook-posts-create` `instagram-mentions-reply` `linkedin-reactions-create` `x-posts-create` `x-liked-posts-create` `youtube-videos-create` | | `DELETE /v1/inbox/posts/{postId}/like` | `DELETE /inbox/posts/{postId}/like`
`DELETE /accounts/{accountId}/bluesky/posts/{itemId}`
`DELETE /accounts/{accountId}/facebook/posts/{itemId}`
`POST /accounts/{accountId}/instagram/mentions/{itemId}/reply`
`DELETE /accounts/{accountId}/linkedin/reactions/{itemId}`
`DELETE /accounts/{accountId}/x/posts/{itemId}`
`DELETE /accounts/{accountId}/x/liked-posts/{itemId}`
`DELETE /accounts/{accountId}/youtube/videos/{itemId}` | `unlike-post` `bluesky-posts-delete` `facebook-posts-delete` `instagram-mentions-reply` `linkedin-reactions-delete` `x-posts-delete` `x-liked-posts-delete` `youtube-videos-delete` | | `POST /v1/inbox/comments/{postId}/{commentId}/private-reply` | `POST /inbox/comments/{commentId}/private-reply`
`POST /accounts/{accountId}/facebook/comments`
`POST /accounts/{accountId}/instagram/comments` | `send-private-reply` `facebook-comments-create` `instagram-comments-create` | ### Twitter Engagement | Zernio | Socialit | MCP tool | |---|---|---| | `POST /v1/twitter/retweet` | `POST /accounts/{accountId}/x/retweets`
`POST /accounts/{accountId}/x/posts` | `retweet` `x-posts-create` | | `DELETE /v1/twitter/retweet` | `DELETE /accounts/{accountId}/x/retweets/{tweetId}`
`DELETE /accounts/{accountId}/x/posts/{itemId}` | `unretweet` `x-posts-delete` | | `POST /v1/twitter/bookmark` | `POST /accounts/{accountId}/x/bookmarks`
`POST /accounts/{accountId}/x/posts` | `bookmark-tweet` `x-posts-create` | | `DELETE /v1/twitter/bookmark` | `DELETE /accounts/{accountId}/x/bookmarks/{tweetId}`
`DELETE /accounts/{accountId}/x/posts/{itemId}` | `remove-bookmark` `x-posts-delete` | | `POST /v1/twitter/follow` | `POST /accounts/{accountId}/x/following` | `follow-x-user` | | `DELETE /v1/twitter/follow` | `DELETE /accounts/{accountId}/x/following/{targetUserId}` | `unfollow-x-user` | | `GET /v1/twitter/search` | `GET /accounts/{accountId}/x/search` | `search-tweets` | | `GET /v1/twitter/tweet` | `GET /accounts/{accountId}/x/tweets/{tweetId}`
`GET /accounts/{accountId}/x/posts` | `get-tweet` `x-posts-list` | ### Mentions | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/inbox/mentions` | `GET /inbox/mentions`
`GET /accounts/{accountId}/bluesky/notifications`
`GET /accounts/{accountId}/facebook/mentions`
`GET /accounts/{accountId}/linkedin/mentions`
`GET /accounts/{accountId}/threads/mentions`
`GET /accounts/{accountId}/tiktok/mentioned-posts`
`GET /accounts/{accountId}/x/mentions` | `list-mentions` `bluesky-notifications-list` `facebook-mentions-list` `linkedin-mentions-list` `threads-mentions-list` `tiktok-mentioned-posts-list` `x-mentions-list` | | `POST /v1/inbox/mentions/reply` | `POST /inbox/mentions/reply`
`POST /accounts/{accountId}/facebook/mentions/{itemId}/reply`
`POST /accounts/{accountId}/instagram/mentions/{itemId}/reply`
`POST /accounts/{accountId}/linkedin/mentions/{itemId}/reply`
`POST /accounts/{accountId}/threads/mentions/{itemId}/reply`
`POST /accounts/{accountId}/tiktok/comment-mentions/{itemId}/reply`
`POST /accounts/{accountId}/x/mentions/{itemId}/reply` | `reply-to-mention` `facebook-mentions-reply` `instagram-mentions-reply` `linkedin-mentions-reply` `threads-mentions-reply` `tiktok-comment-mentions-reply` `x-mentions-reply` | ### Reviews | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/inbox/reviews` | `GET /inbox/reviews`
`GET /accounts/{accountId}/facebook/reviews`
`GET /accounts/{accountId}/google-business/reviews` | `list-reviews` `facebook-reviews-list` `google-business-reviews-list` | | `POST /v1/inbox/reviews/{reviewId}/reply` | `POST /inbox/reviews/{reviewId}/reply`
`POST /accounts/{accountId}/facebook/reviews/{itemId}/reply`
`POST /accounts/{accountId}/google-business/reviews/{itemId}/reply` | `reply-to-review` `facebook-reviews-reply` `google-business-reviews-reply` | | `DELETE /v1/inbox/reviews/{reviewId}/reply` | `DELETE /inbox/reviews/{reviewId}/reply`
`POST /accounts/{accountId}/facebook/reviews/{itemId}/reply`
`POST /accounts/{accountId}/google-business/reviews/{itemId}/reply` | `delete-review-reply` `facebook-reviews-reply` `google-business-reviews-reply` | ### Contacts | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/contacts` | `GET /contacts` | `list-contacts` | | `POST /v1/contacts` | `POST /contacts` | `create-contact` | | `GET /v1/contacts/{contactId}` | `GET /contacts/{id}` | `get-contact` | | `PATCH /v1/contacts/{contactId}` | `PATCH /contacts/{id}` | `update-contact` | | `DELETE /v1/contacts/{contactId}` | `DELETE /contacts/{id}` | `delete-contact` | | `GET /v1/contacts/{contactId}/channels` | `GET /contacts/{id}/channels` | `list-contact-channels` | | `POST /v1/contacts/bulk` | `POST /contacts/bulk` | `bulk-create-contacts` | ### Custom Fields | Zernio | Socialit | MCP tool | |---|---|---| | `PUT /v1/contacts/{contactId}/fields/{slug}` | `PUT /contacts/{id}/fields/{slug}` | `set-contact-field-value` | | `DELETE /v1/contacts/{contactId}/fields/{slug}` | `DELETE /contacts/{id}/fields/{slug}` | `clear-contact-field-value` | | `GET /v1/custom-fields` | `GET /custom-fields` | `list-custom-fields` | | `POST /v1/custom-fields` | `POST /custom-fields` | `create-custom-field` | | `PATCH /v1/custom-fields/{fieldId}` | `PATCH /custom-fields/{id}` | `update-custom-field` | | `DELETE /v1/custom-fields/{fieldId}` | `DELETE /custom-fields/{id}` | `delete-custom-field` | ### Broadcasts | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/broadcasts` | `GET /broadcasts` | `list-broadcasts` | | `POST /v1/broadcasts` | `POST /broadcasts` | `create-broadcast` | | `GET /v1/broadcasts/{broadcastId}` | `GET /broadcasts/{id}` | `get-broadcast` | | `PATCH /v1/broadcasts/{broadcastId}` | `PATCH /broadcasts/{id}` | `update-broadcast` | | `DELETE /v1/broadcasts/{broadcastId}` | `DELETE /broadcasts/{id}` | `delete-broadcast` | | `POST /v1/broadcasts/{broadcastId}/send` | `POST /broadcasts/{id}/send` | `send-broadcast` | | `POST /v1/broadcasts/{broadcastId}/schedule` | `POST /broadcasts/{id}/schedule` | `schedule-broadcast` | | `POST /v1/broadcasts/{broadcastId}/cancel` | `POST /broadcasts/{id}/cancel` | `cancel-broadcast` | | `GET /v1/broadcasts/{broadcastId}/recipients` | `GET /broadcasts/{id}/recipients` | `list-broadcast-recipients` | | `POST /v1/broadcasts/{broadcastId}/recipients` | `POST /broadcasts/{id}/recipients` | `add-broadcast-recipients` | ### Support Assistant | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/support/runs` | `GET /support/runs` | `list-support-runs` | | `POST /v1/support/runs` | `POST /support/runs` | `ask-support-question` | | `GET /v1/support/runs/{runId}` | `GET /support/runs/{id}` | `get-support-run` | ### Workflows | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/workflows` | `GET /workflows` | `list-workflows` | | `POST /v1/workflows` | `POST /workflows` | `create-workflow` | | `GET /v1/workflows/{workflowId}` | `GET /workflows/{id}` | `get-workflow` | | `PATCH /v1/workflows/{workflowId}` | `PATCH /workflows/{id}` | `update-workflow` | | `DELETE /v1/workflows/{workflowId}` | `DELETE /workflows/{id}` | `delete-workflow` | | `POST /v1/workflows/{workflowId}/activate` | `POST /workflows/{id}/activate` | `activate-workflow` | | `POST /v1/workflows/{workflowId}/pause` | `POST /workflows/{id}/pause` | `pause-workflow` | | `GET /v1/workflows/{workflowId}/executions` | `GET /workflows/{id}/executions` | `list-workflow-executions` | | `POST /v1/workflows/{workflowId}/executions` | `POST /workflows/{id}/executions` | `start-workflow-execution` | | `POST /v1/workflows/{workflowId}/trigger` | `POST /workflows/{id}/trigger` | `trigger-workflow` | | `GET /v1/workflows/{workflowId}/executions/{executionId}/events` | `GET /workflows/{id}/executions/{executionId}/events` | `list-workflow-execution-events` | | `POST /v1/workflows/{workflowId}/duplicate` | `POST /workflows/{id}/duplicate` | `duplicate-workflow` | | `GET /v1/workflows/{workflowId}/versions` | `GET /workflows/{id}/versions` | `list-workflow-versions` | | `GET /v1/workflows/{workflowId}/versions/{version}` | `GET /workflows/{id}/versions/{version}` | `get-workflow-version` | | `POST /v1/workflows/{workflowId}/versions/{version}/restore` | `POST /workflows/{id}/versions/{version}/restore` | `restore-workflow-version` | ### Sequences | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/sequences` | `GET /sequences` | `list-sequences` | | `POST /v1/sequences` | `POST /sequences` | `create-sequence` | | `GET /v1/sequences/{sequenceId}` | `GET /sequences/{id}` | `get-sequence` | | `PATCH /v1/sequences/{sequenceId}` | `PATCH /sequences/{id}` | `update-sequence` | | `DELETE /v1/sequences/{sequenceId}` | `DELETE /sequences/{id}` | `delete-sequence` | | `POST /v1/sequences/{sequenceId}/activate` | `POST /sequences/{id}/activate` | `activate-sequence` | | `POST /v1/sequences/{sequenceId}/pause` | `POST /sequences/{id}/pause` | `pause-sequence` | | `POST /v1/sequences/{sequenceId}/enroll` | `POST /sequences/{id}/enroll` | `enroll-sequence-contacts` | | `DELETE /v1/sequences/{sequenceId}/enroll/{contactId}` | `DELETE /sequences/{id}/enroll/{contactId}` | `unenroll-sequence-contact` | | `GET /v1/sequences/{sequenceId}/enrollments` | `GET /sequences/{id}/enrollments` | `list-sequence-enrollments` | ### Comment Automations | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/comment-automations` | `GET /comment-automations` | `list-comment-automations` | | `POST /v1/comment-automations` | `POST /comment-automations` | `create-comment-automation` | | `GET /v1/comment-automations/{automationId}` | `GET /comment-automations/{id}` | `get-comment-automation` | | `PATCH /v1/comment-automations/{automationId}` | `PATCH /comment-automations/{id}` | `update-comment-automation` | | `DELETE /v1/comment-automations/{automationId}` | `DELETE /comment-automations/{id}` | `delete-comment-automation` | | `GET /v1/comment-automations/{automationId}/logs` | `GET /comment-automations/{id}/logs` | `list-comment-automation-logs` | ### Ad Campaigns | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/ads` | `GET /ads` | `list-ads` | | `GET /v1/ads/recommendations` | `GET /ads/recommendations` | `list-ad-recommendations` | | `POST /v1/ads/recommendations/apply` | `POST /ads/recommendations/apply` | `apply-ad-recommendations` | | `POST /v1/ads/recommendations/dismiss` | `POST /ads/recommendations/dismiss` | `dismiss-ad-recommendations` | | `GET /v1/ads/bid-strategies` | `GET /ads/bid-strategies` | `list-ad-bid-strategies` | | `POST /v1/ads/bid-strategies` | `POST /ads/bid-strategies` | `create-ad-bid-strategy` | | `PATCH /v1/ads/bid-strategies/{strategyId}` | `PATCH /ads/bid-strategies/{strategyId}` | `update-ad-bid-strategy` | | `GET /v1/ads/shared-budgets` | `GET /ads/shared-budgets` | `list-ad-shared-budgets` | | `POST /v1/ads/shared-budgets` | `POST /ads/shared-budgets` | `create-ad-shared-budget` | | `GET /v1/ads/keywords` | `GET /ads/keywords` | `list-ad-keywords` | | `POST /v1/ads/keywords` | `POST /ads/keywords` | `add-ad-keywords` | | `PATCH /v1/ads/keywords/{keywordId}` | `PATCH /ads/keywords/{id}` | `update-ad-keyword` | | `DELETE /v1/ads/keywords/{keywordId}` | `DELETE /ads/keywords/{id}` | `delete-ad-keyword` | | `GET /v1/ads/campaigns` | `GET /ads/campaigns` | `list-ad-campaigns` | | `POST /v1/ads/campaigns` | `POST /ads/campaigns` | `create-ad-campaign` | | `PUT /v1/ads/campaigns/{campaignId}/status` | `PATCH /ads/campaigns/{id}/status` | `set-ad-campaign-status` | | `GET /v1/ads/campaigns/{campaignId}/ad-schedule` | `GET /ads/campaigns/{id}/ad-schedule` | `get-ad-campaign-schedule` | | `PUT /v1/ads/campaigns/{campaignId}/ad-schedule` | `PUT /ads/campaigns/{id}/ad-schedule` | `replace-ad-campaign-schedule` | | `GET /v1/ads/campaigns/{campaignId}/bidding` | `GET /ads/campaigns/{id}/bidding` | `get-ad-campaign-bidding` | | `GET /v1/ads/campaigns/{campaignId}` | `GET /ads/campaigns/{id}` | `get-ad-campaign` | | `PUT /v1/ads/campaigns/{campaignId}` | `PATCH /ads/campaigns/{id}` | `update-ad-campaign` | | `DELETE /v1/ads/campaigns/{campaignId}` | `DELETE /ads/campaigns/{id}` | `delete-ad-campaign` | | `GET /v1/ads/campaigns/{campaignId}/negative-keywords` | `GET /ads/campaigns/{id}/negative-keywords` | `list-ad-campaign-negative-keywords` | | `PUT /v1/ads/campaigns/{campaignId}/negative-keywords` | `PUT /ads/campaigns/{id}/negative-keywords` | `replace-ad-campaign-negative-keywords` | | `POST /v1/ads/campaigns/bulk-status` | `POST /ads/campaigns/bulk-status` | `bulk-set-ad-campaign-status` | | `POST /v1/ads/campaigns/{campaignId}/duplicate` | `POST /ads/campaigns/{id}/duplicate` | `duplicate-ad-campaign` | | `GET /v1/ads/campaigns/{campaignId}/targeting` | `GET /ads/campaigns/{id}/targeting` | `get-ad-campaign-targeting` | | `PUT /v1/ads/campaigns/{campaignId}/targeting` | `PUT /ads/campaigns/{id}/targeting` | `replace-ad-campaign-targeting` | | `GET /v1/ads/ad-sets` | `GET /ads/ad-sets` | `list-ad-sets` | | `POST /v1/ads/ad-sets` | `POST /ads/ad-sets` | `create-ad-set` | | `POST /v1/ads/ad-sets/{adSetId}/duplicate` | `POST /ads/ad-sets/{id}/duplicate` | `duplicate-ad-set` | | `POST /v1/ads/{adId}/duplicate` | `POST /ads/{id}/duplicate` | `duplicate-ad` | | `GET /v1/ads/ad-sets/{adSetId}` | `GET /ads/ad-sets/{id}` | `get-ad-set` | | `PUT /v1/ads/ad-sets/{adSetId}` | `PATCH /ads/ad-sets/{id}` | `update-ad-set` | | `DELETE /v1/ads/ad-sets/{adSetId}` | `DELETE /ads/ad-sets/{id}` | `delete-ad-set` | | `PUT /v1/ads/ad-sets/{adSetId}/status` | `PATCH /ads/ad-sets/{id}/status` | `set-ad-set-status` | | `GET /v1/ads/tree` | `GET /ads/tree` | `get-ad-tree` | | `GET /v1/ads/timeline` | `GET /ads/timeline` | `get-ad-timeline` | | `GET /v1/ads/{adId}` | `GET /ads/{id}` | `get-ad` | | `PUT /v1/ads/{adId}` | `PATCH /ads/{id}` | `update-ad` | | `DELETE /v1/ads/{adId}` | `DELETE /ads/{id}` | `delete-ad` | | `PUT /v1/ads/{adId}/status` | `PATCH /ads/{id}/status` | `set-ad-status` | | `GET /v1/ads/campaigns/{campaignId}/assets` | `GET /ads/campaigns/{id}/assets` | `list-ad-campaign-assets` | | `POST /v1/ads/campaigns/{campaignId}/assets` | `POST /ads/campaigns/{id}/assets` | `add-ad-campaign-assets` | | `PUT /v1/ads/campaigns/{campaignId}/assets` | `PATCH /ads/campaigns/{id}/assets` | `update-ad-campaign-assets` | | `DELETE /v1/ads/campaigns/{campaignId}/assets` | `DELETE /ads/campaigns/{id}/assets` | `remove-ad-campaign-assets` | | `GET /v1/ads/ad-sets/{adSetId}/assets` | `GET /ads/ad-sets/{id}/assets` | `list-ad-set-assets` | | `POST /v1/ads/ad-sets/{adSetId}/assets` | `POST /ads/ad-sets/{id}/assets` | `add-ad-set-assets` | | `PUT /v1/ads/ad-sets/{adSetId}/assets` | `PATCH /ads/ad-sets/{id}/assets` | `update-ad-set-assets` | | `DELETE /v1/ads/ad-sets/{adSetId}/assets` | `DELETE /ads/ad-sets/{id}/assets` | `remove-ad-set-assets` | | `GET /v1/ads/{adId}/review` | `GET /ads/{id}/review` | `get-ad-review` | | `GET /v1/ads/campaigns/{campaignId}/negative-keyword-lists` | `GET /ads/campaigns/{id}/negative-keyword-lists` | `list-ad-campaign-negative-keyword-lists` | | `PUT /v1/ads/campaigns/{campaignId}/negative-keyword-lists` | `PUT /ads/campaigns/{id}/negative-keyword-lists` | `replace-ad-campaign-negative-keyword-lists` | | `POST /v1/ads/boost` | `POST /ads/boost` | `boost-ad-post` | | `GET /v1/ads/campaigns/{campaignId}/asset-groups` | `GET /ads/campaigns/{id}/asset-groups` | `list-ad-asset-groups` | | `POST /v1/ads/campaigns/{campaignId}/asset-groups` | `POST /ads/campaigns/{id}/asset-groups` | `create-ad-asset-group` | | `GET /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}` | `GET /ads/campaigns/{id}/asset-groups/{assetGroupId}` | `get-ad-asset-group` | | `PATCH /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}` | `PATCH /ads/campaigns/{id}/asset-groups/{assetGroupId}` | `update-ad-asset-group` | | `DELETE /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}` | `DELETE /ads/campaigns/{id}/asset-groups/{assetGroupId}` | `delete-ad-asset-group` | | `POST /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}/assets` | `POST /ads/campaigns/{id}/asset-groups/{assetGroupId}/assets` | `link-ad-asset-group-assets` | | `PUT /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}/listing-group-filters` | `PUT /ads/campaigns/{id}/asset-groups/{assetGroupId}/listing-group-filters` | `replace-ad-listing-group-filters` | | `POST /v1/ads/create` | `POST /ads` | `create-ad` | | `GET /v1/ads/campaigns/{campaignId}/conversion-goals` | `GET /ads/campaigns/{id}/conversion-goals` | `get-ad-campaign-conversion-goals` | | `PATCH /v1/ads/campaigns/{campaignId}/conversion-goals` | `PATCH /ads/campaigns/{id}/conversion-goals` | `update-ad-campaign-conversion-goals` | ### Ad Insights | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/ads/search-terms` | `GET /ads/search-terms` | `get-ad-search-terms` | | `GET /v1/ads/local-services/leads` | `GET /ads/local-services/leads` | `list-local-services-leads` | | `GET /v1/ads/local-services/leads/{leadId}/conversations` | `GET /ads/local-services/leads/{leadId}/conversations` | `list-local-services-lead-conversations` | | `GET /v1/ads/campaigns/{campaignId}/analytics` | `GET /ads/campaigns/{id}/analytics` | `get-ad-campaign-analytics` | | `POST /v1/ads/keywords/ideas` | `POST /ads/keywords/ideas` | `generate-ad-keyword-ideas` | | `POST /v1/ads/keywords/historical-metrics` | `POST /ads/keywords/historical-metrics` | `get-ad-keyword-historical-metrics` | | `GET /v1/ads/insights` | `GET /ads/insights` | `get-ad-insights` | | `POST /v1/ads/insights/reports` | `POST /ads/insights/reports` | `create-ad-insights-report` | | `GET /v1/ads/insights/reports/{reportRunId}` | `GET /ads/insights/reports/{reportId}` | `get-ad-insights-report` | | `GET /v1/ads/{adId}/analytics` | `GET /ads/{id}/analytics` | `get-ad-analytics` | | `GET /v1/ads/tiktok-smart-plus-materials` | `GET /ads/tiktok-smart-plus-materials` | `get-tiktok-smart-plus-materials` | ### Ad Creatives | Zernio | Socialit | MCP tool | |---|---|---| | `POST /v1/ads/preview` | `POST /ads/preview` | `preview-ad-creative` | | `GET /v1/ads/{adId}/preview` | `GET /ads/{id}/preview` | `get-ad-previews` | | `GET /v1/ads/{adId}/media` | `GET /ads/{id}/media` | `get-ad-media` | | `GET /v1/ads/tiktok-identities` | `GET /ads/tiktok-identities` | `list-tiktok-ad-identities` | | `GET /v1/ads/creatives` | `GET /ads/creatives` | `list-ad-creatives` | | `POST /v1/ads/creatives` | `POST /ads/creatives` | `create-ad-creative` | | `GET /v1/ads/creatives/{creativeId}` | `GET /ads/creatives/{creativeId}` | `get-ad-creative` | | `PUT /v1/ads/creatives/{creativeId}` | `PATCH /ads/creatives/{creativeId}` | `rename-ad-creative` | | `DELETE /v1/ads/creatives/{creativeId}` | `DELETE /ads/creatives/{creativeId}` | `delete-ad-creative` | | `GET /v1/ads/images` | `GET /ads/images` | `list-ad-images` | | `POST /v1/ads/images` | `POST /ads/images` | `upload-ad-image` | | `GET /v1/ads/videos` | `GET /ads/videos` | `list-ad-videos` | | `POST /v1/ads/videos` | `POST /ads/videos` | `upload-ad-video` | | `GET /v1/ads/videos/{videoId}` | `GET /ads/videos/{videoId}` | `get-ad-video` | | `DELETE /v1/ads/videos/{videoId}` | `DELETE /ads/videos/{videoId}` | `delete-ad-video` | | `GET /v1/ads/partnership-content` | `GET /ads/partnership-content` | `list-ad-partnership-content` | | `GET /v1/ads/partnership-permissions` | `GET /ads/partnership-permissions` | `list-ad-partnership-permissions` | | `POST /v1/ads/partnership-permissions` | `POST /ads/partnership-permissions` | `set-ad-partnership-permission` | ### Tracking Tags | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/ads/{adId}/tracking-tags` | `GET /ads/{adId}/tracking-tags` | `get-ad-tracking-params` | | `PATCH /v1/ads/{adId}/tracking-tags` | `PATCH /ads/{adId}/tracking-tags` | `set-ad-tracking-params` | | `GET /v1/accounts/{accountId}/tracking-tags` | `GET /ads/accounts/{adAccountId}/tracking-tags` | `list-tracking-tags` | | `POST /v1/accounts/{accountId}/tracking-tags` | `POST /ads/accounts/{adAccountId}/tracking-tags` | `create-tracking-tag` | | `GET /v1/accounts/{accountId}/tracking-tags/{tagId}` | `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}` | `get-tracking-tag` | | `PATCH /v1/accounts/{accountId}/tracking-tags/{tagId}` | `PATCH /ads/accounts/{adAccountId}/tracking-tags/{tagId}` | `update-tracking-tag` | | `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts` | `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/shared-accounts` | `list-tracking-tag-shared-accounts` | | `POST /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts` | `POST /ads/accounts/{adAccountId}/tracking-tags/{tagId}/shared-accounts` | `share-tracking-tag` | | `DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts` | `DELETE /ads/accounts/{adAccountId}/tracking-tags/{tagId}/shared-accounts/{sharedAccountId}` | `unshare-tracking-tag` | | `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/events` | `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events` | `list-tracking-tag-events` | | `POST /v1/accounts/{accountId}/tracking-tags/{tagId}/events` | `POST /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events` | `create-tracking-tag-event` | | `PATCH /v1/accounts/{accountId}/tracking-tags/{tagId}/events/{eventId}` | `PATCH /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events/{eventId}` | `update-tracking-tag-event` | | `DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/events/{eventId}` | `DELETE /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events/{eventId}` | `delete-tracking-tag-event` | | `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/users` | `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/users` | `list-tracking-tag-users` | | `POST /v1/accounts/{accountId}/tracking-tags/{tagId}/users` | `POST /ads/accounts/{adAccountId}/tracking-tags/{tagId}/users` | `assign-tracking-tag-user` | | `DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/users/{userId}` | `DELETE /ads/accounts/{adAccountId}/tracking-tags/{tagId}/users/{userId}` | `remove-tracking-tag-user` | | `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/partners` | `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/partners` | `list-tracking-tag-partners` | | `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/diagnostics` | `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/diagnostics` | `get-tracking-tag-diagnostics` | | `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/stats` | `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/stats` | `get-tracking-tag-stats` | ### Ad Accounts | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/ads/{adId}/comments` | `GET /ads/{adId}/comments` | `list-ad-comments` | | `POST /v1/ads/{adId}/comments/{commentId}/reply` | `POST /ads/{adId}/comments/{commentId}/reply` | `reply-ad-comment` | | `POST /v1/ads/{adId}/comments/{commentId}/hide` | `POST /ads/{adId}/comments/{commentId}/hide` | `hide-ad-comment` | | `DELETE /v1/ads/{adId}/comments/{commentId}` | `DELETE /ads/{adId}/comments/{commentId}` | `delete-ad-comment` | | `GET /v1/ads/business-centers` | `GET /ads/connections/{connectionId}/business-centers` | `list-ad-business-centers` | | `GET /v1/ads/activity` | `GET /ads/accounts/{adAccountId}/activity` | `list-ad-account-activity` | | `GET /v1/ads/studies` | `GET /ads/accounts/{adAccountId}/studies` | `list-ad-studies` | | `GET /v1/ads/instagram-accounts` | `GET /ads/accounts/{adAccountId}/instagram-accounts` | `list-ad-instagram-accounts` | | `GET /v1/ads/instagram-posts` | `GET /ads/accounts/{adAccountId}/instagram-posts` | `list-ad-instagram-posts` | | `GET /v1/ads/advertisable-applications` | `GET /ads/accounts/{adAccountId}/advertisable-applications` | `list-advertisable-applications` | | `GET /v1/ads/ios-fourteen-campaign-limits` | `GET /ads/accounts/{adAccountId}/ios-campaign-limits` | `get-ios-campaign-limits` | | `GET /v1/ads/businesses` | `GET /ads/connections/{connectionId}/businesses` | `list-ad-businesses` | | `GET /v1/ads/businesses/users` | `GET /ads/connections/{connectionId}/businesses/{businessId}/users` | `list-ad-business-users` | | `GET /v1/ads/page-users` | `GET /ads/connections/{connectionId}/pages/{pageId}/users` | `list-ad-page-users` | | `POST /v1/ads/page-users` | `POST /ads/connections/{connectionId}/pages/{pageId}/users` | `assign-ad-page-user` | | `DELETE /v1/ads/page-users` | `DELETE /ads/connections/{connectionId}/pages/{pageId}/users/{userId}` | `remove-ad-page-user` | | `GET /v1/ads/labels` | `GET /ads/accounts/{adAccountId}/labels` | `list-ad-labels` | | `POST /v1/ads/labels` | `POST /ads/accounts/{adAccountId}/labels` | `create-ad-label` | | `PATCH /v1/ads/labels/{labelId}` | `PATCH /ads/accounts/{adAccountId}/labels/{labelId}` | `update-ad-label` | | `DELETE /v1/ads/labels/{labelId}` | `DELETE /ads/accounts/{adAccountId}/labels/{labelId}` | `delete-ad-label` | | `POST /v1/ads/labels/{labelId}/assignments` | `POST /ads/accounts/{adAccountId}/labels/{labelId}/assignments` | `attach-ad-label` | | `DELETE /v1/ads/labels/{labelId}/assignments` | `DELETE /ads/accounts/{adAccountId}/labels/{labelId}/assignments` | `detach-ad-label` | | `GET /v1/ads/high-demand-periods` | `GET /ads/accounts/{adAccountId}/high-demand-periods` | `list-high-demand-periods` | | `POST /v1/ads/high-demand-periods` | `POST /ads/accounts/{adAccountId}/high-demand-periods` | `create-high-demand-period` | | `GET /v1/ads/value-rule-sets` | `GET /ads/accounts/{adAccountId}/value-rule-sets` | `list-value-rule-sets` | | `POST /v1/ads/value-rule-sets` | `POST /ads/accounts/{adAccountId}/value-rule-sets` | `create-value-rule-set` | | `GET /v1/ads/value-rule-sets/{valueRuleSetId}` | `GET /ads/accounts/{adAccountId}/value-rule-sets/{valueRuleSetId}` | `get-value-rule-set` | | `PUT /v1/ads/value-rule-sets/{valueRuleSetId}` | `PATCH /ads/accounts/{adAccountId}/value-rule-sets/{valueRuleSetId}` | `replace-value-rule-set` | | `DELETE /v1/ads/value-rule-sets/{valueRuleSetId}` | `DELETE /ads/accounts/{adAccountId}/value-rule-sets/{valueRuleSetId}` | `delete-value-rule-set` | | `GET /v1/ads/accounts/negative-keyword-lists` | `GET /ads/accounts/{adAccountId}/negative-keyword-lists` | `list-negative-keyword-lists` | | `POST /v1/ads/accounts/negative-keyword-lists` | `POST /ads/accounts/{adAccountId}/negative-keyword-lists` | `create-negative-keyword-list` | | `GET /v1/ads/accounts/negative-keyword-lists/{listId}` | `GET /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}` | `get-negative-keyword-list` | | `PUT /v1/ads/accounts/negative-keyword-lists/{listId}` | `PATCH /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}` | `rename-negative-keyword-list` | | `DELETE /v1/ads/accounts/negative-keyword-lists/{listId}` | `DELETE /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}` | `delete-negative-keyword-list` | | `PUT /v1/ads/accounts/negative-keyword-lists/{listId}/keywords` | `PATCH /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}/keywords` | `replace-negative-keyword-list-keywords` | | `GET /v1/ads/accounts/callouts` | `GET /ads/accounts/{adAccountId}/callouts` | `list-account-callouts` | | `POST /v1/ads/accounts/callouts` | `POST /ads/accounts/{adAccountId}/callouts` | `add-account-callouts` | | `PUT /v1/ads/accounts/callouts` | `PATCH /ads/accounts/{adAccountId}/callouts` | `update-account-callouts` | | `DELETE /v1/ads/accounts/callouts` | `DELETE /ads/accounts/{adAccountId}/callouts/{assetId}` | `remove-account-callout` | | `GET /v1/ads/accounts/sitelinks` | `GET /ads/accounts/{adAccountId}/sitelinks` | `list-account-sitelinks` | | `POST /v1/ads/accounts/sitelinks` | `POST /ads/accounts/{adAccountId}/sitelinks` | `add-account-sitelinks` | | `PUT /v1/ads/accounts/sitelinks` | `PATCH /ads/accounts/{adAccountId}/sitelinks` | `update-account-sitelinks` | | `DELETE /v1/ads/accounts/sitelinks` | `DELETE /ads/accounts/{adAccountId}/sitelinks/{assetId}` | `remove-account-sitelink` | | `GET /v1/ads/accounts/structured-snippets` | `GET /ads/accounts/{adAccountId}/structured-snippets` | `list-account-structured-snippets` | | `POST /v1/ads/accounts/structured-snippets` | `POST /ads/accounts/{adAccountId}/structured-snippets` | `add-account-structured-snippets` | | `PUT /v1/ads/accounts/structured-snippets` | `PATCH /ads/accounts/{adAccountId}/structured-snippets` | `update-account-structured-snippets` | | `DELETE /v1/ads/accounts/structured-snippets` | `DELETE /ads/accounts/{adAccountId}/structured-snippets/{assetId}` | `remove-account-structured-snippet` | | `GET /v1/ads/accounts/hierarchy` | `GET /ads/connections/{connectionId}/hierarchy` | `get-ad-manager-hierarchy` | | `POST /v1/ads/accounts/manager-links` | `POST /ads/connections/{connectionId}/manager-links` | `create-ad-manager-link` | | `PATCH /v1/ads/accounts/manager-links` | `PATCH /ads/connections/{connectionId}/manager-links/{managerLinkId}` | `update-ad-manager-link` | | `GET /v1/ads/accounts/users` | `GET /ads/accounts/{adAccountId}/users` | `list-ad-account-users` | | `POST /v1/ads/accounts/users` | `POST /ads/accounts/{adAccountId}/users` | `assign-ad-account-user` | | `DELETE /v1/ads/accounts/users` | `DELETE /ads/accounts/{adAccountId}/users/{userId}` | `remove-ad-account-user` | | `GET /v1/ads/accounts/finance` | `GET /ads/accounts/{adAccountId}/finance` | `get-ad-account-finance` | | `GET /v1/ads/accounts/live` | `GET /ads/accounts/{adAccountId}/live` | `get-ad-account-live` | | `GET /v1/ads/accounts` | `GET /ads/accounts` | `list-ad-accounts` | | `POST /v1/ads/accounts` | `POST /ads/accounts` | `create-ad-account` | | `PATCH /v1/ads/accounts` | `PATCH /ads/accounts/{adAccountId}/settings` | `update-ad-account-settings` | | `GET /v1/ads/dsa-defaults` | `GET /ads/accounts/{adAccountId}/dsa-defaults` | `get-ad-account-dsa-defaults` | | `GET /v1/ads/dsa-recommendations` | `GET /ads/accounts/{adAccountId}/dsa-recommendations` | `get-ad-account-dsa-recommendations` | | `GET /v1/accounts/{accountId}/custom-conversions` | `GET /ads/accounts/{adAccountId}/custom-conversions` | `list-custom-conversions` | | `POST /v1/accounts/{accountId}/custom-conversions` | `POST /ads/accounts/{adAccountId}/custom-conversions` | `create-custom-conversion` | | `GET /v1/ads/pixels` | `GET /ads/accounts/{adAccountId}/pixels` | `list-ad-pixels` | ### Reach and Frequency | Zernio | Socialit | MCP tool | |---|---|---| | `POST /v1/ads/rf-predictions` | `POST /ads/rf-predictions` | `create-ad-reach-frequency-prediction` | | `GET /v1/ads/rf-predictions/{predictionId}` | `GET /ads/rf-predictions/{predictionId}` | `get-ad-reach-frequency-prediction` | | `DELETE /v1/ads/rf-predictions/{predictionId}` | `DELETE /ads/rf-predictions/{predictionId}` | `cancel-ad-reach-frequency-prediction` | | `POST /v1/ads/rf-predictions/{predictionId}/reserve` | `POST /ads/rf-predictions/{predictionId}/reserve` | `reserve-ad-reach-frequency-prediction` | ### Lead Gen | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/ads/leads` | `GET /ads/leads` | `list-leads` | | `GET /v1/ads/lead-forms` | `GET /ads/lead-forms` | `list-lead-forms` | | `POST /v1/ads/lead-forms` | `POST /ads/lead-forms` | `create-lead-form` | | `GET /v1/ads/lead-forms/{formId}` | `GET /ads/lead-forms/{formId}` | `get-lead-form` | | `DELETE /v1/ads/lead-forms/{formId}` | `DELETE /ads/lead-forms/{formId}` | `archive-lead-form` | | `GET /v1/ads/lead-forms/{formId}/leads` | `GET /ads/lead-forms/{formId}/leads` | `list-lead-form-leads` | | `POST /v1/ads/lead-forms/{formId}/test-leads` | `POST /ads/lead-forms/{formId}/test-leads` | `create-test-lead` | | `DELETE /v1/ads/lead-forms/{formId}/test-leads` | `DELETE /ads/lead-forms/{formId}/test-leads` | `delete-test-leads` | ### Ad Targeting | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/ads/interests` | `GET /ads/interests` | `search-ad-interests` | | `GET /v1/ads/targeting/search` | `GET /ads/targeting/search` | `search-ad-targeting` | | `GET /v1/ads/targeting/browse` | `GET /ads/targeting/browse` | `browse-ad-targeting` | | `POST /v1/ads/targeting/reach-estimate` | `POST /ads/targeting/reach-estimate` | `estimate-ad-reach` | | `POST /v1/ads/targeting/bid-pricing` | `POST /ads/targeting/bid-pricing` | `get-ad-bid-pricing` | | `POST /v1/ads/targeting/supply-forecast` | `POST /ads/targeting/supply-forecast` | `get-ad-supply-forecast` | ### Ad Library | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/ads/library` | `GET /ads/library` | `search-ad-library` | ### Product Catalogs | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/ads/catalogs` | `GET /ads/catalogs` | `list-catalogs` | | `POST /v1/ads/catalogs` | `POST /ads/catalogs` | `create-catalog` | | `GET /v1/ads/catalogs/{catalogId}` | `GET /ads/catalogs/{catalogId}` | `get-catalog` | | `DELETE /v1/ads/catalogs/{catalogId}` | `DELETE /ads/catalogs/{catalogId}` | `delete-catalog` | | `GET /v1/ads/catalogs/{catalogId}/products` | `GET /ads/catalogs/{catalogId}/products` | `list-catalog-products` | | `POST /v1/ads/catalogs/{catalogId}/products` | `POST /ads/catalogs/{catalogId}/products` | `create-catalog-product` | | `POST /v1/ads/catalogs/{catalogId}/products/batch` | `POST /ads/catalogs/{catalogId}/products/batch` | `batch-catalog-products` | | `GET /v1/ads/catalogs/{catalogId}/batches/{handle}` | `GET /ads/catalogs/{catalogId}/batches/{handle}` | `get-catalog-batch` | | `GET /v1/ads/catalogs/{catalogId}/products/{productId}` | `GET /ads/catalogs/{catalogId}/products/{productId}` | `get-catalog-product` | | `PUT /v1/ads/catalogs/{catalogId}/products/{productId}` | `PATCH /ads/catalogs/{catalogId}/products/{productId}` | `update-catalog-product` | | `DELETE /v1/ads/catalogs/{catalogId}/products/{productId}` | `DELETE /ads/catalogs/{catalogId}/products/{productId}` | `delete-catalog-product` | | `GET /v1/ads/catalogs/{catalogId}/feeds` | `GET /ads/catalogs/{catalogId}/feeds` | `list-catalog-feeds` | | `POST /v1/ads/catalogs/{catalogId}/feeds` | `POST /ads/catalogs/{catalogId}/feeds` | `create-catalog-feed` | | `GET /v1/ads/catalogs/{catalogId}/feeds/{feedId}/uploads` | `GET /ads/catalogs/{catalogId}/feeds/{feedId}/uploads` | `list-catalog-feed-uploads` | | `POST /v1/ads/catalogs/{catalogId}/feeds/{feedId}/uploads` | `POST /ads/catalogs/{catalogId}/feeds/{feedId}/uploads` | `create-catalog-feed-upload` | | `GET /v1/ads/catalogs/{catalogId}/product-sets` | `GET /ads/catalogs/{catalogId}/product-sets` | `list-product-sets` | | `POST /v1/ads/catalogs/{catalogId}/product-sets` | `POST /ads/catalogs/{catalogId}/product-sets` | `create-product-set` | | `PUT /v1/ads/catalogs/{catalogId}/product-sets/{productSetId}` | `PATCH /ads/catalogs/{catalogId}/product-sets/{productSetId}` | `update-product-set` | | `DELETE /v1/ads/catalogs/{catalogId}/product-sets/{productSetId}` | `DELETE /ads/catalogs/{catalogId}/product-sets/{productSetId}` | `delete-product-set` | ### Ad Audiences | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/ads/audiences` | `GET /ads/audiences` | `list-ad-audiences` | | `POST /v1/ads/audiences` | `POST /ads/audiences` | `create-ad-audience` | | `GET /v1/ads/audiences/{audienceId}` | `GET /ads/audiences/{id}` | `get-ad-audience` | | `PUT /v1/ads/audiences/{audienceId}` | `PATCH /ads/audiences/{id}` | `update-ad-audience` | | `DELETE /v1/ads/audiences/{audienceId}` | `DELETE /ads/audiences/{id}` | `delete-ad-audience` | | `POST /v1/ads/audiences/{audienceId}/users` | `POST /ads/audiences/{id}/users` | `add-ad-audience-users` | | `POST /v1/ads/audiences/{audienceId}/companies` | `POST /ads/audiences/{id}/companies` | `replace-ad-audience-companies` | ### Conversions | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/ads/conversions/quality` | `GET /ads/conversions/quality` | `get-event-match-quality` | | `POST /v1/ads/conversions` | `POST /ads/conversions` | `send-conversions` | | `POST /v1/ads/conversions/adjustments` | `POST /ads/conversions/adjustments` | `adjust-conversions` | | `GET /v1/ads/conversions/actions` | `GET /ads/accounts/{adAccountId}/conversion-actions` | `list-conversion-actions` | | `POST /v1/ads/conversions/actions` | `POST /ads/accounts/{adAccountId}/conversion-actions` | `create-conversion-action` | | `GET /v1/ads/conversions/goals` | `GET /ads/accounts/{adAccountId}/conversion-goals` | `list-conversion-goals` | | `PATCH /v1/ads/conversions/goals` | `PATCH /ads/accounts/{adAccountId}/conversion-goals` | `update-conversion-goals` | | `PATCH /v1/ads/conversions/actions/{actionId}` | `PATCH /ads/accounts/{adAccountId}/conversion-actions/{actionId}` | `update-conversion-action` | | `GET /v1/ads/conversions/custom-goals` | `GET /ads/accounts/{adAccountId}/custom-conversion-goals` | `list-custom-conversion-goals` | | `POST /v1/ads/conversions/custom-goals` | `POST /ads/accounts/{adAccountId}/custom-conversion-goals` | `create-custom-conversion-goal` | | `PATCH /v1/ads/conversions/custom-goals/{goalId}` | `PATCH /ads/accounts/{adAccountId}/custom-conversion-goals/{goalId}` | `update-custom-conversion-goal` | | `DELETE /v1/ads/conversions/custom-goals/{goalId}` | `DELETE /ads/accounts/{adAccountId}/custom-conversion-goals/{goalId}` | `delete-custom-conversion-goal` | | `GET /v1/accounts/{accountId}/conversion-destinations` | `GET /ads/accounts/{adAccountId}/conversion-destinations` | `list-conversion-destinations` | | `POST /v1/accounts/{accountId}/conversion-destinations` | `POST /ads/accounts/{adAccountId}/conversion-destinations` | `create-conversion-destination` | | `GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}` | `GET /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}` | `get-conversion-destination` | | `PATCH /v1/accounts/{accountId}/conversion-destinations/{destinationId}` | `PATCH /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}` | `update-conversion-destination` | | `DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}` | `DELETE /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}` | `delete-conversion-destination` | | `GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations` | `GET /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/associations` | `list-conversion-associations` | | `POST /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations` | `POST /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/associations` | `add-conversion-associations` | | `DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations` | `DELETE /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/associations` | `remove-conversion-associations` | | `GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}/metrics` | `GET /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/metrics` | `get-conversion-metrics` | ### Messaging Ads | Zernio | Socialit | MCP tool | |---|---|---| | `POST /v1/ads/messaging` | `POST /ads/messaging` | `create-messaging-ad` | | `POST /v1/ads/call` | `POST /ads/call` | `create-call-ad` | ### Tools | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/tools/tiktok/download` | `GET /tools/tiktok/download`
`GET /accounts/{accountId}/tiktok/download` | `download-tik-tok-video` `tiktok-download-list` | ### Changelog | Zernio | Socialit | MCP tool | |---|---|---| | `GET /v1/changelog` | `GET /changelog` | `list-changelog` | --- Source: https://socialit.com/docs/migrating-from-zernio/ # Moving to the new Socialit > What changes when Socialit moves to its new platform on 16 November 2026, from the maintenance window to the app, the desktop and mobile apps, and API integrations. On **Monday, 16 November 2026** Socialit moves to its new platform: a rebuilt app, a new REST API and new desktop and mobile apps. Your workspaces, accounts and posts move over automatically. This page covers the maintenance before the switch, what to do once it's done, and what to change if you built on the Socialit API. ## Maintenance from 13 to 16 November From **Friday, 13 November** until **Monday, 16 November 2026** Socialit is down while we move every workspace to the new platform. - **The app** (web, desktop and mobile) shows a maintenance notice or errors, and you can't sign in. - **The API** answers with errors (`500`, `502` or `503`). Nothing you send during the window is stored, so pause your jobs or let them retry later. - **Scheduled posts** move over with everything else. A post that falls due during the window is published once we're back if it's at most a day late. An older one is marked as failed (missed schedule), and you can retry it in one click (or with `POST /v1/posts/{id}/retry`). > **Before Friday:** Publish anything that can't wait before the maintenance starts, and avoid scheduling new posts for 13 to 16 November. ## What moves over Everything moves over automatically. You don't need to export or import anything. | Moves over | Notes | |---|---| | Your account | Same email and password. | | Workspaces, profiles and team | Members keep their roles and profile access; pending invitations still work. | | Connected social accounts | They keep working. Reconnect only the ones marked **Needs reconnect**. | | Posts | Published, scheduled and drafts, with their media and per-network results. | | Media, queues, templates and account groups | Unchanged. | | Inbox conversations, comments and contacts | Unchanged. | | API keys | Every `sk_live_…` key keeps working. | | Plan and billing | Your plan, limits and payments carry over unchanged. | Two things don't move over: **sign-ins**, so every browser and device signs in once more, and connections or sign-in codes that were still in progress when the maintenance began. ## Posting first, more features step by step The new Socialit starts with **Posting**: composing, scheduling and publishing to the networks you use today, queues, the media library, templates, profiles and your team. That's what Socialit did before, now on the new platform. The new features come next, one at a time: - **when they're stable**, after they've run well in production, and - **when the networks approve them**: many features need permissions (scopes) that each network reviews before Socialit may use them. Until a feature is on, the app marks it **Soon**, and the API answers `403` with the code `feature_unavailable`. Each new feature is announced in the [changelog](/changelog/). ## In the app 1. **Sign in** at [app.socialit.com](https://app.socialit.com) with your email and password. If you used to sign in with Google, choose **Email me a sign-in code** (or **Forgot your password?** to set one). 2. **Check your accounts** under **Accounts**. Reconnect any account marked **Needs reconnect**. 3. **Check your schedule** under **Posts**. Retry any post that failed because it was due during the maintenance. 4. **Update your bookmarks.** Pages now live under your workspace, for example `app.socialit.com//compose`. The new app also brings two-factor sign-in and passkeys: turn them on under **Security** in your account settings. ## Desktop and mobile apps The installed Socialit apps keep working with the new platform. Sign in again after the move. A new version of the apps follows shortly after the switch: update when the App Store, Google Play or the macOS app offers it. App Store subscriptions carry over. ## API integrations The base URL, the keys and the IDs stay the same: - Base URL: `https://api.socialit.com/v1` - Authentication: `Authorization: Bearer sk_live_…` with your existing keys ([Authentication](/docs/authentication/)) - IDs: every `ws_…`, `pro_…`, `sa_…`, `pst_…`, `med_…` and other ID stays the same ([Objects and IDs](/docs/concepts/objects/)) The request and response formats changed, and 40 of the 74 endpoints moved. Update your code with the sections below so it's ready when the new API goes live on 16 November. ### Responses | | Before | Now | |---|---|---| | Lists | `{ "posts": [ … ] }` | `{ "object": "list", "data": [ … ] }` | | One object | `{ "post": { … } }` | The object itself | | Results per account | `targets` | `postings` | | Errors | `{ "error": "NotFound" }` | `{ "error": { "type", "code", … } }` | | Post statuses | 5 | 8 | - **Lists are paginated.** Before, a list returned everything at once. Now follow `next_page_url` while `has_more` is true ([Pagination](/docs/api-reference/pagination/)). - **Objects come unwrapped**, with their type in `object` (for example `"object": "post"`). - **Errors share one envelope:** `{ "error": { "type", "code", "message", "param", "errors" }, "request_id" }`. Branch on `error.code`, and quote `request_id` when you contact us ([Errors](/docs/api-reference/errors/)). - **Posts have three new statuses** next to `draft`, `scheduled`, `publishing`, `published` and `failed`: `pending_approval`, `partially_published` and `cancelled`. ### Creating and updating posts | Before | Now | |---|---| | `target_account_ids` | `account_ids` | | `config_by_platform` | `platform_options` | | `publish: true` | `publish_now: true` | | `content`, `media_ids`, `scheduled_at`, `queue_id`, `quote_post_id`, `strict` | Unchanged | > **Old field names are ignored, not rejected:** The API drops fields it doesn't know. A post sent with `target_account_ids` and `publish: true` is saved as an empty **draft** and answers `201`, so nothing is published and nothing fails. Rename the fields above before you send posts to the new API, and check the `status` of the post you get back. When listing posts, `from`, `to`, `status` and `profile_id` keep their names; `unscheduled` is gone (use `status=draft`). See [Publishing](/docs/publishing/) for everything a post can do now. ### Endpoints that moved **Accounts** - `GET /v1/social-accounts` → `GET /v1/accounts` - `GET`, `PATCH /v1/social-accounts/{id}` → `GET`, `PATCH /v1/accounts/{id}` - `GET /v1/social-accounts/{id}/health` → `GET /v1/accounts/{id}/health` **Account groups** - `GET`, `POST /v1/groups` → `GET`, `POST /v1/account-groups` - `GET`, `PATCH`, `DELETE /v1/groups/{id}` → same methods on `/v1/account-groups/{id}` - `GET /v1/groups/{id}/members` → `account_ids` in `GET /v1/account-groups/{id}` - `POST /v1/groups/{id}/members` → `POST /v1/account-groups/{id}/accounts` - `DELETE /v1/groups/{id}/members/{account_id}` → `DELETE /v1/account-groups/{id}/accounts/{account_id}` **Postings** (a post's result on one account) - `GET /v1/social-postings` → `GET /v1/postings` - `GET /v1/social-postings/{id}` → `GET /v1/postings/{id}` - `GET /v1/posts/{id}/social-postings` → `GET /v1/postings?post_id={id}`, or `postings` in `GET /v1/posts/{id}` **Media** - `POST /v1/media/upload` → `POST /v1/media/upload-direct`: multipart with a `file` field. For large files use `POST /v1/media/presign`. **Comments** - `GET /v1/comments?account_id=` → `GET /v1/inbox/comments?account_id=` - `GET`, `POST /v1/comments/{post_id}` → `GET`, `POST /v1/inbox/posts/{post_id}/comments` - `DELETE /v1/comments/{post_id}/{comment_id}` → `DELETE /v1/inbox/comments/{comment_id}` - `POST /v1/comments/{post_id}/{comment_id}/hide` → `POST /v1/inbox/comments/{comment_id}/hide` - `POST`, `DELETE /v1/comments/{post_id}/{comment_id}/like` → `POST`, `DELETE /v1/inbox/comments/{comment_id}/like` **Conversations and messages** - `GET`, `POST /v1/conversations` → `GET`, `POST /v1/inbox/conversations` - `GET /v1/conversations/{id}` → `GET /v1/inbox/conversations/{id}` - `GET`, `POST /v1/conversations/{id}/messages` → `GET`, `POST /v1/inbox/conversations/{id}/messages` - `POST /v1/conversations/{id}/typing` → `POST /v1/inbox/conversations/{id}/typing` - `POST`, `DELETE /v1/messages/{id}/reactions` → `POST`, `DELETE /v1/inbox/conversations/{conversation_id}/messages/{id}/reactions` **Reviews** - `GET /v1/reviews` → `GET /v1/inbox/reviews` - `POST`, `DELETE /v1/reviews/{id}/reply` → `POST`, `DELETE /v1/inbox/reviews/{id}/reply` **Connecting accounts** - `GET`, `POST /v1/connect/grants/{grant_id}` → `GET /v1/connect/pending-data` and `POST /v1/connect/select` ([Connecting accounts](/docs/connecting-accounts/)) **Validation** - `POST /v1/validate/post` → `POST /v1/tools/validate/post` - `POST /v1/validate/post-length` → `POST /v1/tools/validate/post-length` - `POST /v1/validate/media` → `POST /v1/tools/validate/media` - `POST /v1/validate/subreddit` → `GET /v1/tools/validate/subreddit?name=` Comment and post IDs in the inbox endpoints are the ones those endpoints return. Posts, profiles, queues, media, contacts, custom fields and `GET /v1/connect/{platform}` keep their paths, with the new formats above. ### New in the API - **Idempotency keys** on every create and send, so a retry never posts twice ([Idempotency](/docs/api-reference/idempotency/)). - **Webhooks** with signed events, instead of polling ([Webhooks](/docs/webhooks/)). - **OAuth 2.1** for apps that act for other Socialit users ([Authentication](/docs/authentication/)). - **MCP server** at `https://api.socialit.com/mcp`: every operation as a tool for Claude, Cursor or ChatGPT ([MCP server](/docs/mcp/)). > **Let an agent do it:** Point Claude, Cursor or another MCP client at this page (`/docs/migrating-to-v1.md`) and your integration's code: the sections above give it every rename. ## Questions Write to [support@socialit.com](mailto:support@socialit.com) or reply to our email about the move. We read every message. --- Source: https://socialit.com/docs/migrating-to-v1/ # Networks > The 14 networks Socialit supports, their platform keys, and what each one can do in the unified API and in Focus mode. Every network works through the same endpoints. Each guide lists post types and limits, options for `platform_options`, inbox and analytics support, and the [Focus mode](/docs/focus-mode/) resources. | Network | Platform key | Connect | |---|---|---| | [Facebook](/docs/networks/facebook/) | `facebook` | OAuth, Page picker | | [Instagram](/docs/networks/instagram/) | `instagram` | OAuth (professional accounts) | | [X](/docs/networks/x/) | `x` (alias `twitter`) | OAuth 2.0 with PKCE | | [LinkedIn](/docs/networks/linkedin/) | `linkedin` | OAuth, profile or Company Page | | [Threads](/docs/networks/threads/) | `threads` | OAuth | | [Bluesky](/docs/networks/bluesky/) | `bluesky` | Handle and app password | | [Pinterest](/docs/networks/pinterest/) | `pinterest` | OAuth, board picker | | [TikTok](/docs/networks/tiktok/) | `tiktok` | OAuth | | [YouTube](/docs/networks/youtube/) | `youtube` | OAuth (Google) | | [Google Business Profile](/docs/networks/google-business/) | `google_business` (alias `googlebusiness`) | OAuth, location picker | | [Reddit](/docs/networks/reddit/) | `reddit` | OAuth | | [Snapchat](/docs/networks/snapchat/) | `snapchat` | OAuth (Public Profile) | | [Discord](/docs/networks/discord/) | `discord` | Bot install | | [Mastodon](/docs/networks/mastodon/) | `mastodon` | OAuth on your server | > **Note:** X bills API usage per call. Socialit passes the cost through at X's rates from prepaid credits; see [pricing](/pricing/). --- Source: https://socialit.com/docs/networks/ # Publishing > Create, schedule, queue and publish posts to every network with one call, then track each account's result, retry, edit or unpublish. A **post** is what you write once. Every account it targets gets a **posting** (`sp_…`) that tracks that network's status, ID, URL and error. A post to Instagram, LinkedIn and X has three postings. The status of the post is the roll-up of its postings. | Toolset | Endpoints | |---|---| | `posts` | [Posts](/docs/api-reference/posts/): create, schedule, retry, edit, unpublish, approvals, notes, postings | | `queues` | [Queues](/docs/api-reference/queues/): recurring time slots per profile | | `media` | [Media](/docs/api-reference/media/): uploads, URLs, folders, usage | | `templates` | [Templates](/docs/api-reference/templates/): reusable content | | `tools` | [Tools](/docs/api-reference/tools/): validation before you publish | ## Create a post `POST /v1/posts` creates a draft, schedules it, puts it in a queue or publishes it now. Pick the targets with `account_ids`, a whole `profile_id` or an account `group_id` (both filtered by `platforms`), or `targets` for per-account overrides. ```bash curl -X POST https://api.socialit.com/v1/posts \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: launch-2026-10-20" \ -H "Content-Type: application/json" \ -d '{ "content": "We just shipped Focus mode.", "account_ids": ["sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "sa_7Hc2Lm9Qw4Rt6Yp1Xn3Vb8Kd5Sz"], "media_ids": ["med_9Lq2Vx7Bn4Mc1Zr8Tw3Ys6Hd0Kp"], "scheduled_at": "2026-10-20T09:00:00", "timezone": "Europe/Prague" }' ``` | You send | Result | |---|---| | `draft: true` (or no schedule field) | Saved as a `draft` | | `publish_now: true`, or `scheduled_at` in the past | Published right away (`publishing` in the 201 response) | | `scheduled_at` (+ `timezone`) | Scheduled. Without an offset, the time is wall clock in `timezone` | | `queue: true` or `queue_id` | The next free slot of that queue (or the profile's default queue) | Precedence is `draft` > `publish_now` > `queue` > `scheduled_at`. Publishing is asynchronous: poll `GET /v1/posts/{id}` or listen for webhooks. Posts are unlimited on every plan; the per-account daily cap of your plan answers `429 posts_per_day_limit`. Turn an existing draft into a scheduled post with `POST /v1/posts/{id}/schedule` (`scheduled_at`, `publish_now`, `queue` or `queue_id`), and stop a scheduled one with `POST /v1/posts/{id}/cancel`. ## Lifecycle | Post status | Meaning | |---|---| | `draft` | Not scheduled | | `pending_approval` | Waiting for an approver (workspace approvals on) | | `scheduled` | Waiting for its time | | `publishing` | At least one posting is still running | | `published` | Every posting published | | `partially_published` | Some postings published, others failed | | `failed` | No posting published | | `cancelled` | Cancelled, or every published posting was unpublished | Postings are `pending`, `processing` (accepted by the network, final ID not known yet: Instagram and Threads containers, TikTok, Reddit media), `published`, `failed` or `cancelled`. A failed posting has `error`, `error_code` and an `error_category` such as `auth_expired`, `user_content`, `platform_rate_limit` or `quota_exhausted`. Temporary network errors are retried automatically; fix the cause of permanent ones and call `POST /v1/posts/{id}/retry` (optionally with `account_ids`). ## Per-network options `content` and the media apply to every target. Network-only settings go in `platform_options`, keyed by platform, and are validated against each network's schema. `GET /v1/posts/platform-options` returns every schema. ```json { "content": "Focus mode walkthrough", "account_ids": ["sa_youtube…", "sa_instagram…", "sa_x…"], "media_ids": ["med_video…"], "first_comment": "Full changelog in the replies", "platform_options": { "youtube": { "title": "Focus mode walkthrough", "privacyStatus": "public", "selfDeclaredMadeForKids": false }, "instagram": { "shareToFeed": true }, "x": { "replySettings": "following" } }, "targets": [{ "account_id": "sa_x…", "content": "Focus mode is live. Thread below." }] } ``` - Keys can be camelCase (as in the schemas) or snake_case. Unknown options are dropped with a `warnings` entry, or rejected with `422` when you send `strict: true`. - `thread_items` continues the post as a thread on X, Threads, Bluesky and Mastodon. - `quote_post_id`, `quote_url` and `reply_to_url` publish as a quote or a reply. - `recycle` re-posts evergreen content on an interval, with optional `content_variations`. Each [network guide](/docs/networks/) lists the post types, limits and options. Some networks require an explicit choice (TikTok privacy level, YouTube made-for-kids) and have no defaults on purpose. ## Media Upload once, reuse the ID everywhere: 1. `POST /v1/media/presign` with `filename` and `content_type` returns an `upload_url`. 2. `PUT` the file to `upload_url` with the same `Content-Type` (no auth header). 3. Call `POST /v1/media/{id}/complete`, or just reference the media in a post. `POST /v1/media` registers a public URL instead, and `media_urls` on a post does the same inline. Videos get a thumbnail and preview; `GET /v1/media/usage` reports storage against your plan. ## Validate first - `POST /v1/tools/validate/post` checks a draft against every target (length, media, options) and returns `errors` and `warnings` per account. - `POST /v1/tools/validate/post-length` counts characters the way each network does. - `POST /v1/tools/validate/media` checks a file against each network's limits. `POST /v1/posts` runs the same checks and answers `422 validation_failed` with `errors` keyed by field, such as `platform_options.x.replySettings` or `media_ids[1]`. ## After publishing | Goal | Endpoint | |---|---| | Edit the live post (where the network allows it) | `POST /v1/posts/{id}/edit` | | Change YouTube video metadata | `POST /v1/posts/{id}/update-metadata` | | Delete it on the networks | `POST /v1/posts/{id}/unpublish` | | Delete it in Socialit (optionally on networks too) | `DELETE /v1/posts/{id}?delete_on_network=true` | | Duplicate it as a draft | `POST /v1/posts/{id}/duplicate` | Networks without edit or delete answer `422 edit_not_supported` or `422 unpublish_not_supported`. ## Queues, approvals and bulk upload - **Queues** have weekly slots (`day_of_week`, `time`) in their timezone. `GET /v1/queues/next-slot` and `GET /v1/queues/preview` show where the next posts would land. - **Approvals:** with `require_approval` on (`PATCH /v1/publishing/settings`), posts by members and profile-restricted keys go to `pending_approval`. Approvers call `POST /v1/posts/{id}/approve` or `/reject`. Internal notes live under `/v1/posts/{id}/notes`. - **Bulk upload:** `POST /v1/posts/bulk-upload` takes a CSV (up to 5,000 rows); add `?dry_run=true` to validate only. ## Webhooks `post.scheduled`, `post.publishing`, `post.published`, `post.partially_published`, `post.failed`, `post.cancelled`, `post.edited`, `post.unpublished`, `post.deleted`, `post.recycled`, the approval events and `posting.published` / `posting.failed` per account. See [Webhook events](/docs/api-reference/webhook-events/). --- Source: https://socialit.com/docs/publishing/ # Quickstart > Create an API key, find your connected accounts and publish one post to three networks. This quickstart takes about five minutes. You need a Socialit account (Free works) with at least one connected social account. 1. **Create an API key.** In the app, open **Manage → API keys** and select **Create key**. Copy the secret (`sk_live_…`); it is shown once. See [Authentication](/docs/authentication/). 2. **Find your accounts.** List the connected accounts and note the IDs (`sa_…`) you want to publish to. ```bash curl https://api.socialit.com/v1/accounts \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` 3. **Upload media (optional).** Upload an image or video once and reuse its `med_…` ID in any post. 4. **Create the post.** One request publishes to every account in `account_ids`. Set `scheduled_at` to schedule it, or leave it out to publish now. 5. **Listen for the result.** Add a [webhook](/docs/webhooks/) for `post.published` and `post.failed`, or poll `GET /v1/posts/{id}`. ## Create the post **cURL** ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: launch-2026-10-14" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": ["sa_instagram…", "sa_linkedin…", "sa_x…"], "scheduled_at": "2026-10-14T09:00:00.000Z", "first_comment": "#focusmode" }' ``` **Node.js** ```js const res = await fetch('https://api.socialit.com/v1/posts', { method: 'POST', headers: { Authorization: `Bearer ${process.env.SOCIALIT_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'launch-2026-10-14', }, body: JSON.stringify({ content: 'Focus mode is live. Open one account, use everything.', account_ids: ['sa_instagram…', 'sa_linkedin…', 'sa_x…'], scheduled_at: '2026-10-14T09:00:00.000Z', }), }); const post = await res.json(); ``` **Python** ```python post = requests.post( "https://api.socialit.com/v1/posts", headers={"Authorization": f"Bearer {os.environ['SOCIALIT_API_KEY']}"}, json={ "content": "Focus mode is live. Open one account, use everything.", "account_ids": ["sa_instagram…", "sa_linkedin…", "sa_x…"], "scheduled_at": "2026-10-14T09:00:00.000Z", }, ).json() ``` The response is the post with one *posting* per target account: ```json { "object": "post", "id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd", "status": "scheduled", "scheduled_at": "2026-10-14T09:00:00.000Z", "postings": [ { "object": "posting", "platform": "instagram", "status": "pending" }, { "object": "posting", "platform": "linkedin", "status": "pending" }, { "object": "posting", "platform": "x", "status": "pending" } ] } ``` > **Note:** If any target network would reject the post (too long for X, a video too short for TikTok), Socialit answers `422 validation_failed` with the reason per field, before anything is published. See [Errors](/docs/api-reference/errors/). ## Next steps - [Publishing](/docs/publishing/): queues, drafts, per-network options, editing and deleting. - [Webhooks](/docs/webhooks/): receive `post.published` and verify signatures. - [Network guides](/docs/networks/): what each network accepts. --- Source: https://socialit.com/docs/quickstart/ # UI modes and Focus mode > Manage mode for admins, Member mode for everyone, and Focus mode for one account on one network, in the app and the API. The Socialit app has two modes, and Focus mode is reachable from both. ## Manage mode For workspace admins: administration and oversight across every profile. Profiles, members and access, billing and usage, API keys, webhooks, request logs, account health and workspace analytics, plus integrations such as ad accounts. ## Member mode For everyone, and the default for non-admins. It covers the profiles you are attached to: compose, calendar, queue, posts, media, inbox, analytics, contacts, broadcasts, automations and accounts. A profile switcher shows all your profiles or one of them. Switch modes with the **Member / Manage** control at the top of the sidebar. Admins see both; other roles see Member mode only. ## Focus mode Focus mode opens **one connected account on one network**, full screen. Its goal is to expose everything that network's official API allows for that account. On YouTube, for example: videos and Shorts, playlists, captions, comment moderation, live broadcasts, memberships, channel branding and sections, and deep analytics. Open it from the **Focus** launcher in the sidebar. The navigation becomes the network's own, and the accent color becomes the network's color. What you see depends on the permissions the account granted; when one is missing, Focus says which and offers to reconnect. ## Focus mode in the API Every Focus resource is an API resource too. ```bash curl https://api.socialit.com/v1/accounts/sa_7Yt2…/focus \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` ```json { "object": "focus_manifest", "account_id": "sa_7Yt2…", "platform": "youtube", "resources": [ { "key": "videos", "label": "Videos", "actions": ["list", "get", "create", "update", "delete"] }, { "key": "playlists", "label": "Playlists", "actions": ["list", "create", "update", "delete", "addVideo"] }, { "key": "captions", "label": "Captions", "actions": ["list", "create", "delete"] } ], "missing_scopes": [] } ``` Then work with a resource generically: - `GET /v1/accounts/{id}/focus/{resource}` lists items. - `GET /v1/accounts/{id}/focus/{resource}/{item_id}` gets one. - `POST`, `PATCH` and `DELETE` create, update and delete. - `POST /v1/accounts/{id}/focus/{resource}/{item_id}/{action}` runs an action, such as adding a video to a playlist. Every resource also has typed endpoints, such as `/v1/accounts/{id}/youtube/playlists`, under the Focus · Network tags of the [API reference](/docs/api-reference/#group-focus-mode). The [Focus mode guide](/docs/focus-mode/) covers the manifest, actions, scope upgrades and MCP toolsets. Each [network guide](/docs/networks/) lists its Focus resources. --- Source: https://socialit.com/docs/ui-modes/ # Webhooks > Receive signed events for posts, accounts, the inbox, messaging, ads and billing, verify their signatures and handle retries. Webhooks send a `POST` request to your URL when something happens in your workspace. Create endpoints in **Manage → Webhooks** or with the [Webhooks API](/docs/api-reference/webhooks/) (MCP toolset `webhooks`), and subscribe to every event or a list. ```bash curl -X POST https://api.socialit.com/v1/webhooks \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production", "url": "https://your-app.com/socialit/webhooks", "events": ["post.published", "post.failed", "message.received"] }' ``` The response includes the signing `secret` (or bring your own with `secret`). `profile_ids` limits an endpoint to events of some profiles; `all_events: true` subscribes to everything, including event types added later. ## Payload Every delivery has the same envelope; `data` depends on the event type. ```json { "id": "evt_9Qw2Lm4Rt6Yp1Xn3Vb8Kd5SzHc2", "object": "event", "type": "post.published", "created_at": "2026-10-14T09:00:04.512Z", "workspace_id": "ws_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "test": false, "data": { "post": { "object": "post", "id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd", "status": "published", "postings": [{ "object": "posting", "platform": "instagram", "status": "published", "url": "https://www.instagram.com/p/…" }] } } } ``` Headers: `X-Socialit-Signature`, `X-Socialit-Timestamp`, `X-Socialit-Event` (the type) and `X-Socialit-Delivery` (the delivery ID). ## Event types Socialit emits about 90 event types across posts, accounts, the inbox, contacts and automations, ads, analytics and billing. The [Webhook events reference](/docs/api-reference/webhook-events/) lists every one with its payload, generated from the same catalog the API validates subscriptions against (`GET /v1/events/names`). `GET /v1/events` is the event log: the same payloads, kept for replay and debugging. ## Verify the signature Every delivery has two headers: - `X-Socialit-Timestamp`: Unix time in seconds when the delivery was signed. - `X-Socialit-Signature`: hex HMAC-SHA256 of `${timestamp}.${body}` with your endpoint's secret. Compute the HMAC over the **raw** request body, compare in constant time, and reject timestamps older than five minutes to stop replays. **Node.js** ```js export function verify(rawBody, headers, secret) { const timestamp = headers['x-socialit-timestamp']; const signature = headers['x-socialit-signature']; if (!timestamp || !signature || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex'); return signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); } ``` **Python** ```python def verify(raw_body: bytes, headers, secret: str) -> bool: timestamp = headers.get("X-Socialit-Timestamp") signature = headers.get("X-Socialit-Signature") if not timestamp or not signature or abs(time.time() - int(timestamp)) > 300: return False expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(signature, expected) ``` **PHP** ```php 300) return false; $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret); return hash_equals($expected, $signature); } ``` ## Responding and retries Answer with any `2xx` status quickly, and do slow work after responding. Socialit retries failed deliveries after **5 minutes, 30 minutes, 2 hours and 5 hours, then every 12 hours**, up to **11 attempts**. An endpoint that keeps failing for 3 days is disabled automatically. Deliveries can arrive more than once and out of order: use the event `id` to deduplicate and `created_at` to order. ## Tools - `POST /v1/webhooks/{id}/test` sends a test event of the type you choose. - `GET /v1/webhooks/{id}/deliveries` lists recent deliveries with status codes and response bodies. - `POST /v1/webhooks/deliveries/{id}/redeliver` sends one again; `POST /v1/webhooks/{id}/retry-failed` retries all failed ones. - `POST /v1/webhooks/{id}/reset-secret` rotates the signing secret. --- Source: https://socialit.com/docs/webhooks/ # Socialit documentation > Guides and references for the Socialit REST API, webhooks, the MCP server and every network Socialit supports. Socialit publishes, schedules and answers on 14 social networks through one app, one REST API and one MCP server. These docs cover everything you need to build on it. - [Quickstart](/docs/quickstart/)Publish your first post to three networks in five minutes. - [Authentication](/docs/authentication/)API keys, OAuth tokens and permissions. - [Connecting accounts](/docs/connecting-accounts/)Hosted and headless connect flows for your users. ## Guides - [Publishing](/docs/publishing/)Posts, postings, scheduling, queues, media and per-network options. - [Unified inbox](/docs/inbox/)Conversations, comments, reviews and mentions, with real-time webhooks. - [Analytics](/docs/analytics/)Post metrics, account insights, best time and inbox analytics. - [Focus mode](/docs/focus-mode/)Everything a network allows for one account, generic or typed. - [CRM and automations](/docs/crm-automations/)Contacts, broadcasts, sequences, workflows and comment-to-DM. - [Ads](/docs/ads/)Campaigns, boosts, audiences, insights, leads and pixels. - [Webhooks](/docs/webhooks/)Signed events, verification and retries. - [MCP server](/docs/mcp/)Connect Claude, Cursor, ChatGPT and other AI agents. - [Moving to the new Socialit](/docs/migrating-to-v1/)The maintenance, the app and every API change. - [Migrating from Zernio](/docs/migrating-from-zernio/)Every Zernio endpoint mapped to Socialit. ## Networks Every network has a guide with its post types, limits, options and Focus mode resources. Start with [all networks](/docs/networks/), or jump to [Instagram](/docs/networks/instagram/), [YouTube](/docs/networks/youtube/), [TikTok](/docs/networks/tiktok/) or [LinkedIn](/docs/networks/linkedin/). ## API reference The [API reference](/docs/api-reference/) documents every endpoint of the REST API v1, grouped by area, with every [webhook event](/docs/api-reference/webhook-events/). It is generated from our OpenAPI 3.1 document, which you can also fetch from `https://api.socialit.com/v1/openapi.json` to generate a client in any language. > **Docs for AI assistants:** Every page has a Markdown version: add `.md` to the URL. The whole documentation is at [/docs/llms.txt](/docs/llms.txt) and [/docs/llms-full.txt](/docs/llms-full.txt). --- Source: https://socialit.com/docs/ # Facebook > Facebook Pages, Reels and Messenger from one API. Publish Page posts, Reels and Stories, answer Messenger and comments in the unified inbox, and read Page insights. Connect once with Facebook Login and pick the Pages you manage. Platform key: `facebook` · Connection: oauth ## Post types - Text: up to 63206 characters - Images: up to 10 per post - Video - Reels - Stories - Links (Link previews and link carousels (2–10 cards)) ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_facebook…" ], "first_comment": "Questions? Ask below.", "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "facebook": { "link": "https://socialit.com/product/focus-mode/" } } }' ``` ## Focus mode - Page posts, Reels and Stories with per-post targeting - Messenger: persistent menu, greeting, ice breakers - Comment moderation: hide, like, reply, private reply - Recommendations (reviews) with replies - Page and post insights - Lead forms and Meta Ads for the same Page --- Source: https://socialit.com/docs/networks/facebook/ # Instagram > Instagram Reels, carousels and DMs without the Graph API homework. Feed posts, carousels, Reels and Stories go out through the same request as every other network. Socialit handles media containers, processing waits and publish state, then brings comments, mentions and DMs into one inbox. Platform key: `instagram` · Connection: oauth ## Post types - Images (Feed posts, caption up to 2,200 characters) - Carousels: up to 10 per post - Reels (Reels and trial Reels, cover frame, audio name) - Stories ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_instagram…" ], "media_ids": [ "med_7Hk2…" ], "first_comment": "#focusmode #socialmedia", "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "instagram": { "collaborators": [ "northwind.studio" ], "share_to_feed": true } } }' ``` ## Focus mode - Reels, trial Reels and Stories with covers and audio - Collaborators and user tags - DM inbox with ice breakers and quick replies - Comments: reply, hide, private reply, comment-to-DM - Account insights and audience demographics - Business discovery for public business accounts ## Notes - Requires an Instagram professional (Business or Creator) account. --- Source: https://socialit.com/docs/networks/instagram/ # X > Post to X without living in the developer console. Schedule posts, threads, polls and media to X through Socialit. We run the OAuth app, the media upload steps and the rate limits. X bills API usage per call, so we pass it through at cost from prepaid credits. Platform key: `x` · Connection: oauth ## Post types - Text: up to 280 characters (Up to 25,000 characters with X Premium) - Images: up to 4 per post - Video - Threads - Polls ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_x…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "x": { "reply_settings": "following" } } }' ``` ## Focus mode - Threads, quote posts, replies and polls - Likes, reposts and bookmarks - Follows, lists and mutes - Direct messages - Mentions and search - Post metrics: impressions, engagements, link clicks ## Notes - X API usage is billed by X per call. Socialit passes it through at cost from prepaid credits; every other network is included in your plan. --- Source: https://socialit.com/docs/networks/x/ # LinkedIn > LinkedIn profiles and Company Pages, one request shape. Publish long-form text, multi-image posts, video, document carousels and polls to personal profiles and the Company Pages you administer. Comments on Page posts land in the unified inbox. Platform key: `linkedin` · Connection: oauth ## Post types - Text: up to 3000 characters - Images: up to 20 per post - Video - Documents (PDF, PPT and DOC carousels up to 300 pages) - Polls ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_linkedin…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "linkedin": { "visibility": "PUBLIC" } } }' ``` ## Focus mode - Company Page administration and admin roles - Document carousels and polls - Comments and reactions on Page posts - Follower, visitor and share statistics - Reshares and mentions - LinkedIn Ads campaigns for the same Page --- Source: https://socialit.com/docs/networks/linkedin/ # Threads > Threads, alongside the rest of your Meta stack. Post text, images, video, carousels and multi-part threads with reply controls and topic tags. Replies and mentions arrive in the unified inbox next to Instagram and Facebook. Platform key: `threads` · Connection: oauth ## Post types - Text: up to 500 characters - Images - Video - Carousels: up to 10 per post - Threads ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_threads…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "threads": { "reply_control": "everyone" } } }' ``` ## Focus mode - Multi-part threads and topic tags - Reply controls per post - Replies: reply, hide, delete - Mentions - Post and profile insights --- Source: https://socialit.com/docs/networks/threads/ # Bluesky > Bluesky publishing without AT Protocol homework. Connect with a handle and an app password. Socialit builds facets for links and mentions, uploads blobs, posts threads and keeps chat, replies and mentions in the unified inbox. Platform key: `bluesky` · Connection: credentials ## Post types - Text: up to 300 characters - Images: up to 4 per post - Video - Threads ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_bluesky…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "bluesky": { "langs": [ "en" ] } } }' ``` ## Focus mode - Threads, languages and content labels - Chat (direct messages) - Replies, likes and reposts - Follows and lists - Post engagement ## Notes - Uses an app password, never your main Bluesky password. --- Source: https://socialit.com/docs/networks/bluesky/ # Pinterest > Create Pins without a second publishing stack. Publish image and video Pins with titles, destination links, boards and board sections. Read Pin and account analytics next to the rest of your channels. Platform key: `pinterest` · Connection: oauth ## Post types - Pins (Image or video Pins with title, link and board) - Images - Video ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_pinterest…" ], "media_ids": [ "med_7Hk2…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "pinterest": { "board_id": "brd_…", "title": "Focus mode in 60 seconds", "link": "https://socialit.com/" } } }' ``` ## Focus mode - Boards and board sections - Pins with links, alt text and covers - Pin and account analytics - Pinterest Ads campaigns --- Source: https://socialit.com/docs/networks/pinterest/ # TikTok > TikTok videos and photo carousels, posted for you. Direct-post videos and photo carousels or send them to the creator’s TikTok inbox as drafts. Socialit shows the creator’s posting limits, privacy options and interaction toggles the way TikTok requires. Platform key: `tiktok` · Connection: oauth ## Post types - Video (3 seconds to 10 minutes, direct post or draft) - Carousels: up to 35 per post (Photo mode carousels) ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_tiktok…" ], "media_ids": [ "med_7Hk2…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "tiktok": { "privacy_level": "PUBLIC_TO_EVERYONE", "disable_duet": false, "disable_stitch": false, "is_ai_generated": false } } }' ``` ## Focus mode - Creator info and posting limits - Privacy level, duet, stitch and comment toggles - Commercial content and AI-generated disclosures - Comments: reply, hide, pin (business accounts) - Business messaging inbox - Video and account insights ## Notes - Comments and DMs require a TikTok Business account; TikTok does not offer business messaging in the EEA, Switzerland and the UK. --- Source: https://socialit.com/docs/networks/tiktok/ # YouTube > Your YouTube channel, every part of it. Upload videos and Shorts with full metadata and scheduled premieres, then switch to Focus mode for the rest of the channel: playlists, captions, comment moderation, live, memberships, branding and deep analytics. Platform key: `youtube` · Connection: oauth ## Post types - Video (Title, description, tags, category, privacy, thumbnail) - Shorts (Detected automatically from vertical video) ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_youtube…" ], "media_ids": [ "med_7Hk2…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "youtube": { "title": "Focus mode walkthrough", "privacy_status": "public", "self_declared_made_for_kids": false, "category_id": "28", "tags": [ "socialit", "focus mode" ] } } }' ``` ## Focus mode - Video studio: uploads, Shorts, thumbnails, scheduling - Playlists and channel sections - Captions and subtitles - Comment moderation queue - Live broadcasts and live chat - Memberships and channel branding - Analytics: views, watch time, retention, demographics, traffic sources --- Source: https://socialit.com/docs/networks/youtube/ # Google Business Profile > Every location, every review, one place. Publish updates, events and offers to one location or hundreds at once, reply to reviews from the unified inbox, and track location performance and the searches people use to find you. Platform key: `google_business` · Connection: oauth ## Post types - Text: up to 1500 characters (Updates with a call-to-action button) - Events - Offers - Images: up to 1 per post ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_googlebusiness…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "google_business": { "topic_type": "OFFER", "call_to_action": { "type": "LEARN_MORE", "url": "https://socialit.com/" } } } }' ``` ## Focus mode - Locations: hours, attributes, services, place action links - Reviews: reply and delete replies - Posts: updates, events and offers - Photos and food menus - Performance and search keywords ## Notes - Google retired per-post insights; Socialit reports location-level performance instead. --- Source: https://socialit.com/docs/networks/google-business/ # Reddit > Post to subreddits that actually accept your post. Socialit checks each subreddit’s rules, flairs and post requirements before you publish, then tracks score and comments and brings replies and messages into the inbox. Platform key: `reddit` · Connection: oauth ## Post types - Text (Self posts with title, flair, NSFW and spoiler flags) - Links - Images - Galleries: up to 20 per post - Video ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_reddit…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "reddit": { "subreddit": "socialmedia", "title": "We built a Focus mode for every network", "flair_id": "flr_…" } } }' ``` ## Focus mode - Subreddit search, rules and post requirements - Flairs, NSFW and spoiler flags - Comments and votes - Private messages and mentions - Moderation queue for subreddits you moderate ## Notes - Reddit’s Data API terms apply; commercial use needs Reddit’s approval. --- Source: https://socialit.com/docs/networks/reddit/ # Snapchat > Stories and Spotlight from your Public Profile. Publish Stories, Saved Stories and Spotlight videos to a Snapchat Public Profile and read views, reach and shares. Platform key: `snapchat` · Connection: oauth ## Post types - Stories - Spotlight - Images: up to 1 per post - Video (5–60 seconds) ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_snapchat…" ], "media_ids": [ "med_7Hk2…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "snapchat": { "content_type": "spotlight" } } }' ``` ## Focus mode - Stories and Saved Stories - Spotlight - Profile insights: views, reach, shares - Snapchat Ads ## Notes - Snap gates the Public Profile API behind an allowlist; access depends on Snap’s approval. --- Source: https://socialit.com/docs/networks/snapchat/ # Discord > Announcements that land in the right channel. Install the bot on your server, pick channels, and publish messages with embeds, files, polls, forum posts and crossposted announcements. Platform key: `discord` · Connection: bot ## Post types - Messages: up to 2000 characters - Embeds: up to 10 per post - Files: up to 10 per post - Polls - Threads (Forum posts and threads) ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_discord…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "discord": { "channel_id": "123456789012345678", "crosspost": true } } }' ``` ## Focus mode - Channels, threads and forum posts - Announcement crossposting - Roles and members - Pins and scheduled events --- Source: https://socialit.com/docs/networks/discord/ # Mastodon > Any Mastodon server, connected in one step. Socialit registers an app on your server automatically, then posts with content warnings, visibility, polls and threads. Mentions, replies and direct messages land in the inbox. Platform key: `mastodon` · Connection: oauth ## Post types - Text: up to 500 characters (Server-dependent; many servers allow more) - Images: up to 4 per post - Video - Polls - Threads ## Example ```bash curl https://api.socialit.com/v1/posts \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "content": "Focus mode is live. Open one account, use everything.", "account_ids": [ "sa_mastodon…" ], "scheduled_at": "2026-10-14T09:00:00.000Z", "platform_options": { "mastodon": { "visibility": "public", "spoiler_text": "" } } }' ``` ## Focus mode - Content warnings, visibility and language - Polls, threads and quote posts - Notifications, mentions and direct messages - Lists, filters and follows - Favourites, boosts and bookmarks --- Source: https://socialit.com/docs/networks/mastodon/ # Accounts API > Profiles, account groups, connected social accounts and connect flows. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List profiles `GET /profiles` Profiles group connected accounts per brand, client or end customer. Filter by name, external_id or is_default. Access: `read` · MCP tool: `list-profiles` · Zernio: `GET /v1/profiles` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of name, created_at, updated_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `name` (string) - `external_id` (string) - `is_default` (boolean) ```bash curl "https://api.socialit.com/v1/profiles" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "profile", "id": "string", "name": "string", "description": "string", "color": "string", "timezone": "Europe/Prague", "external_id": "string", "is_default": true, "account_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a profile `POST /profiles` The first profile of a workspace is the default. external_id is your tenant id (unique per workspace). Access: `admin` · MCP tool: `create-profile` · Zernio: `POST /v1/profiles` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–100 characters) - `description` (string | null; ≤ 500 characters) - `color` (string | null; pattern ^#[0-9A-Fa-f]{6}$): Hex color #RRGGBB - `timezone` (string | null; ≤ 64 characters) - `external_id` (string | null; 1–255 characters) - `is_default` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/profiles" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "description": "string", "color": "string", "timezone": "Europe/Prague", "external_id": "string" }' ``` Response 201: ```json { "object": "profile", "id": "string", "name": "string", "description": "string", "color": "string", "timezone": "Europe/Prague", "external_id": "string", "is_default": true, "account_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get a profile `GET /profiles/{id}` Access: `read` · MCP tool: `get-profile` · Zernio: `GET /v1/profiles/{profileId}` ### Path parameters - `id` (string; required; 1–80 characters): profile id (pro_…) ```bash curl "https://api.socialit.com/v1/profiles/pro_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "profile", "id": "string", "name": "string", "description": "string", "color": "string", "timezone": "Europe/Prague", "external_id": "string", "is_default": true, "account_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a profile `PATCH /profiles/{id}` Set is_default: true to make this the workspace default profile. Access: `admin` · MCP tool: `update-profile` · Zernio: `PUT /v1/profiles/{profileId}` ### Path parameters - `id` (string; required; 1–80 characters): profile id (pro_…) ### Body - `name` (string; 1–100 characters) - `description` (string | null; ≤ 500 characters) - `color` (string | null; pattern ^#[0-9A-Fa-f]{6}$): Hex color #RRGGBB - `timezone` (string | null; ≤ 64 characters) - `external_id` (string | null; 1–255 characters) - `is_default` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/profiles/pro_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "description": "string", "color": "string", "timezone": "Europe/Prague", "external_id": "string" }' ``` Response 200: ```json { "object": "profile", "id": "string", "name": "string", "description": "string", "color": "string", "timezone": "Europe/Prague", "external_id": "string", "is_default": true, "account_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a profile `DELETE /profiles/{id}` Refused with 409 profile_has_accounts while accounts are assigned, unless force=true (the accounts stay connected, unassigned). Access: `admin` · MCP tool: `delete-profile` · Zernio: `DELETE /v1/profiles/{profileId}` ### Path parameters - `id` (string; required; 1–80 characters): profile id (pro_…) ### Query parameters - `force` (boolean) ```bash curl -X DELETE "https://api.socialit.com/v1/profiles/pro_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "profile", "id": "string", "deleted": true } ``` ## List account groups `GET /account-groups` Access: `read` · MCP tool: `list-account-groups` · Zernio: `GET /v1/account-groups` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of name, created_at, updated_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string) - `name` (string) ```bash curl "https://api.socialit.com/v1/account-groups" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "account_group", "id": "string", "name": "string", "description": "string", "color": "string", "profile_id": "string", "account_ids": [ "string" ], "account_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create an account group `POST /account-groups` A named collection of accounts for cross-posting and organization, optionally owned by a profile. Access: `write` · MCP tool: `create-account-group` · Zernio: `POST /v1/account-groups` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–100 characters) - `account_ids` (array of string; ≤ 500 items) - `profile_id` (string | null; ≤ 80 characters) - `description` (string | null; ≤ 500 characters) - `color` (string | null; pattern ^#[0-9A-Fa-f]{6}$): Hex color #RRGGBB ```bash curl -X POST "https://api.socialit.com/v1/account-groups" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "account_ids": [ "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ], "profile_id": "string", "description": "string", "color": "string" }' ``` Response 201: ```json { "object": "account_group", "id": "string", "name": "string", "description": "string", "color": "string", "profile_id": "string", "account_ids": [ "string" ], "account_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get an account group `GET /account-groups/{id}` Access: `read` · MCP tool: `get-account-group` ### Path parameters - `id` (string; required; 1–80 characters): group id (grp_…) ```bash curl "https://api.socialit.com/v1/account-groups/grp_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_group", "id": "string", "name": "string", "description": "string", "color": "string", "profile_id": "string", "account_ids": [ "string" ], "account_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update an account group `PATCH /account-groups/{id}` account_ids replaces the membership. Access: `write` · MCP tool: `update-account-group` · Zernio: `PUT /v1/account-groups/{groupId}` ### Path parameters - `id` (string; required; 1–80 characters): group id (grp_…) ### Body - `name` (string; 1–100 characters) - `account_ids` (array of string; ≤ 500 items) - `profile_id` (string | null; ≤ 80 characters) - `description` (string | null; ≤ 500 characters) - `color` (string | null; pattern ^#[0-9A-Fa-f]{6}$): Hex color #RRGGBB ```bash curl -X PATCH "https://api.socialit.com/v1/account-groups/grp_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "account_ids": [ "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ], "profile_id": "string", "description": "string", "color": "string" }' ``` Response 200: ```json { "object": "account_group", "id": "string", "name": "string", "description": "string", "color": "string", "profile_id": "string", "account_ids": [ "string" ], "account_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete an account group `DELETE /account-groups/{id}` Access: `write` · MCP tool: `delete-account-group` · Zernio: `DELETE /v1/account-groups/{groupId}` ### Path parameters - `id` (string; required; 1–80 characters): group id (grp_…) ```bash curl -X DELETE "https://api.socialit.com/v1/account-groups/grp_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_group", "id": "string", "deleted": true } ``` ## Add accounts to an account group `POST /account-groups/{id}/accounts` Access: `write` · MCP tool: `add-account-group-accounts` ### Path parameters - `id` (string; required; 1–80 characters): group id (grp_…) ### Body - `account_ids` (array of string; required; 1–500 items) ```bash curl -X POST "https://api.socialit.com/v1/account-groups/grp_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/accounts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "account_ids": [ "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ] }' ``` Response 200: ```json { "object": "account_group", "id": "string", "name": "string", "description": "string", "color": "string", "profile_id": "string", "account_ids": [ "string" ], "account_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Remove an account from an account group `DELETE /account-groups/{id}/accounts/{accountId}` Access: `write` · MCP tool: `remove-account-group-account` ### Path parameters - `id` (string; required; 1–80 characters): group id (grp_…) - `accountId` (string; required; 1–80 characters): socialAccount id (sa_…) ```bash curl -X DELETE "https://api.socialit.com/v1/account-groups/grp_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_group", "id": "string", "name": "string", "description": "string", "color": "string", "profile_id": "string", "account_ids": [ "string" ], "account_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List connected accounts `GET /accounts` Filter with platform, profile_id (or none), group_id, status, account_type, search, or .= filters. Access: `read` · MCP tool: `list-accounts` · Zernio: `GET /v1/accounts` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, updated_at, platform, username, display_name, status) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `platform` (string) - `profile_id` (string): pro_… or none for unassigned accounts - `group_id` (string) - `status` (string; one of active, needs_reconnect) - `account_type` (string; one of profile, page, organization, channel) - `search` (string; ≤ 200 characters) ```bash curl "https://api.socialit.com/v1/accounts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Health of every account `GET /accounts/health` Summary plus per-account health. live=true probes every token at the network (slower). Access: `read` · MCP tool: `get-accounts-health` · Zernio: `GET /v1/accounts/health` ### Query parameters - `profile_id` (string) - `platform` (string) - `status` (string; one of healthy, warning, error) - `live` (boolean) - `page` (integer; ≥ 1) - `limit` (integer; 1–100) ```bash curl "https://api.socialit.com/v1/accounts/health" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "account_health", "account_id": "string", "platform": "string", "username": "string", "display_name": "string", "profile_id": "string", "status": "healthy", "can_post": true, "can_fetch_analytics": true, "token_valid": true, "token_expires_at": "2026-10-13T09:00:00.000Z", "needs_reconnect": true, "token": { "valid": true, "strategy": "string", "expires_at": "2026-10-13T09:00:00.000Z", "needs_refresh": true, "detail": "string" }, "permissions": { "posting": [ { "scope": null, "granted": null, "required": null } ], "analytics": [ { "scope": null, "granted": null, "required": null } ], "optional": [ { "scope": null, "granted": null, "required": null } ], "missing_required": [ "string" ] }, "issues": [ "string" ], "recommendations": [ "string" ], "live": true, "checked_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "summary": { "total": 1, "healthy": 1, "warning": 1, "error": 1, "needs_reconnect": 1 } } ``` ## Follower counts and growth `GET /accounts/follower-stats` Daily follower snapshots per account (filled by the analytics sync), bucketed daily, weekly or monthly. Access: `read` · MCP tool: `get-follower-stats` · Zernio: `GET /v1/accounts/follower-stats` ### Query parameters - `account_ids` (string): Comma separated sa_… ids - `profile_id` (string) - `platform` (string) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `granularity` (string; one of daily, weekly, monthly) ```bash curl "https://api.socialit.com/v1/accounts/follower-stats" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "follower_stats", "date_range": { "from_date": "string", "to_date": "string" }, "granularity": "daily", "accounts": [ { "account_id": "string", "platform": "string", "username": "string", "display_name": "string", "current_followers": 1, "growth": 1, "growth_percentage": 1.5, "last_updated": "2026-10-13T09:00:00.000Z", "stats": { "following": 1, "posts_count": 1 }, "data_points": [ { "date": "string", "followers": 1 } ] } ] } ``` ## Get an account `GET /accounts/{id}` Access: `read` · MCP tool: `get-account` ### Path parameters - `id` (string; required; 1–80 characters): socialAccount id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update an account or move it to another profile `PATCH /accounts/{id}` Local label (name), display_name, username, default_config (per-network publish defaults) and profile_id (move). Access: `write` · MCP tool: `update-account` · Zernio: `PUT /v1/accounts/{accountId}`, `PATCH /v1/accounts/{accountId}` ### Path parameters - `id` (string; required; 1–80 characters): socialAccount id (sa_…) ### Body - `name` (string | null; ≤ 100 characters) - `display_name` (string | null; ≤ 200 characters) - `username` (string | null; ≤ 200 characters) - `profile_id` (string | null; ≤ 80 characters) - `default_config` (object | null) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "display_name": "string", "username": "string", "profile_id": "string", "default_config": {} }' ``` Response 200: ```json { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Disconnect an account `DELETE /accounts/{id}` Revokes the token at the network where supported (and no other account shares the grant), then deletes the account. Access: `write` · MCP tool: `disconnect-account` · Zernio: `DELETE /v1/accounts/{accountId}` ### Path parameters - `id` (string; required; 1–80 characters): socialAccount id (sa_…) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account", "id": "string", "deleted": true, "token_revoked": true } ``` ## Check the health of an account `GET /accounts/{id}/health` Live token probe plus granted-vs-required permissions. A dead token marks the account needs_reconnect. Access: `read` · MCP tool: `get-account-health` · Zernio: `GET /v1/accounts/{accountId}/health` ### Path parameters - `id` (string; required; 1–80 characters): socialAccount id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/health" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_health", "account_id": "string", "platform": "string", "username": "string", "display_name": "string", "profile_id": "string", "status": "healthy", "can_post": true, "can_fetch_analytics": true, "token_valid": true, "token_expires_at": "2026-10-13T09:00:00.000Z", "needs_reconnect": true, "token": { "valid": true, "strategy": "string", "expires_at": "2026-10-13T09:00:00.000Z", "needs_refresh": true, "detail": "string" }, "permissions": { "posting": [ { "scope": "string", "granted": true, "required": true } ], "analytics": [ { "scope": "string", "granted": true, "required": true } ], "optional": [ { "scope": "string", "granted": true, "required": true } ], "missing_required": [ "string" ] }, "issues": [ "string" ], "recommendations": [ "string" ], "live": true, "checked_at": "2026-10-13T09:00:00.000Z" } ``` ## List posts published on the network `GET /accounts/{id}/posts` Recent posts read live from the network, including posts not published through Socialit. Access: `read` · MCP tool: `list-account-platform-posts` · Zernio: `GET /v1/accounts/{accountId}/posts` ### Path parameters - `id` (string; required; 1–80 characters): socialAccount id (sa_…) ### Query parameters - `limit` (integer; 1–100) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/posts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "platform_post", "id": "string", "platform": "string", "content": "string", "url": "https://example.com", "published_at": "2026-10-13T09:00:00.000Z", "media_type": "string", "thumbnail_url": "https://example.com", "metrics": { "likes": 1, "comments": 1, "shares": 1, "views": 1 } } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "last_updated": "2026-10-13T09:00:00.000Z" } ``` ## List connectable networks `GET /connect/platforms` Every connect flow with its connect methods, required inputs and picker step. enabled=true keeps the ones configured on this server. Access: `read` · MCP tool: `list-connect-platforms` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `enabled` (boolean) ```bash curl "https://api.socialit.com/v1/connect/platforms" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "connect_platform", "id": "string", "platform": "string", "name": "string", "enabled": true, "connect_type": "string", "connect_types": [ "string" ], "requires": [ "string" ], "selection": "string", "scope_sets": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Start connecting an account (authorization URL) `GET /connect/{platform}` Returns the network authorization URL. After sign-in the network redirects to Socialit, which connects the account (or shows a picker) and sends the browser to redirect_url. headless=true hands multi-target selections to your own picker. Access: `write` · MCP tool: `get-connect-url` · Zernio: `GET /v1/connect/{platform}` ### Path parameters - `platform` (string; required; 1–40 characters): Network or connect flow (x, facebook, linkedin_org, googlebusiness…) ### Query parameters - `profile_id` (string) - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme - `headless` (boolean) - `scope_set` (string; one of core, focus, revenue, members, content_owner) - `reconnect_account_id` (string) - `account_id` (string): Alias of reconnect_account_id - `login_method` (string; one of instagram_login, facebook_login) - `instance` (string; ≤ 255 characters) - `identifier` (string; ≤ 255 characters) - `locale` (string; ≤ 20 characters) - `force_reauth` (boolean) - `content_owner_id` (string; ≤ 100 characters): YouTube CMS content owner - `discord_mode` (string; one of bot, webhook) - `guild_id` (string; ≤ 40 characters) ```bash curl "https://api.socialit.com/v1/connect/PLATFORM" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connect_url", "platform": "string", "flow": "string", "url": "https://example.com", "auth_url": "https://example.com", "state": "string", "expires_at": "2026-10-13T09:00:00.000Z" } ``` ## Complete a connect flow with code and state `POST /connect/{platform}` Headless completion: exchange the authorization code for the state returned by GET /connect/{platform}. Access: `write` · MCP tool: `complete-connect` · Zernio: `POST /v1/connect/{platform}` ### Path parameters - `platform` (string; required; 1–40 characters): Network or connect flow (x, facebook, linkedin_org, googlebusiness…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `code` (string; required; 1–4096 characters) - `state` (string; required; 1–128 characters) - `iss` (string; ≤ 500 characters) - `profile_id` (string) - `guild_id` (string; ≤ 40 characters) - `permissions` (string; ≤ 40 characters) ```bash curl -X POST "https://api.socialit.com/v1/connect/PLATFORM" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "code": "string", "state": "string", "iss": "string", "profile_id": "string", "guild_id": "string" }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## Connect an account with credentials `POST /connect/{platform}/credentials` Bluesky (identifier + app_password), Mastodon (instance + access_token), Discord (webhook_url). Access: `write` · MCP tool: `connect-with-credentials` ### Path parameters - `platform` (string; required; 1–40 characters): Network or connect flow (x, facebook, linkedin_org, googlebusiness…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string) - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme - `identifier` (string; ≤ 255 characters) - `password` (string; ≤ 500 characters) - `app_password` (string; ≤ 500 characters) - `auth_factor_token` (string; ≤ 100 characters) - `service` (string; ≤ 255 characters) - `instance` (string; ≤ 255 characters) - `access_token` (string; ≤ 4096 characters) - `webhook_url` (string; ≤ 500 characters) ```bash curl -X POST "https://api.socialit.com/v1/connect/PLATFORM/credentials" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "redirect_url": "https://example.com", "identifier": "string", "password": "string", "app_password": "string" }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## Get a pending connection `GET /connect/pending-data` Targets waiting to be picked after a multi-target sign-in (token from the headless redirect or a picker step). Access: `write` · MCP tool: `get-pending-connection` · Zernio: `GET /v1/connect/pending-data` ### Query parameters - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) ```bash curl "https://api.socialit.com/v1/connect/pending-data" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true, "account_id": "string", "details": {} } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" } ``` ## Connect the selected targets of a pending connection `POST /connect/select` Access: `write` · MCP tool: `select-pending-connection` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `token` (string; required; 1–128 characters): Pending connection token (cpt_…) - `target_ids` (array of string; 1–500 items) - `board_id` (string; ≤ 100 characters) - `board_name` (string; ≤ 200 characters) ```bash curl -X POST "https://api.socialit.com/v1/connect/select" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "target_ids": [ "string" ], "board_id": "string", "board_name": "string" }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## List FacebookPage targets of a pending connection `GET /connect/facebook/select-page` Targets found after the network sign-in, to render your own picker (headless connect). Pass the pending token as token or the X-Connect-Token header. Access: `write` · MCP tool: `list-facebook-page-connect-targets` · Zernio: `GET /v1/connect/facebook/select-page` ### Query parameters - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) ```bash curl "https://api.socialit.com/v1/connect/facebook/select-page" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true, "account_id": "string", "details": {} } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" } ``` ## Connect the selected FacebookPage targets `POST /connect/facebook/select-page` Access: `write` · MCP tool: `select-facebook-page-connect-targets` · Zernio: `POST /v1/connect/facebook/select-page` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) - `profile_id` (string) - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme - `target_ids` (array of string; ≤ 500 items) - `page_ids` (array of string; ≤ 500 items) - `page_id` (string; ≤ 100 characters) ```bash curl -X POST "https://api.socialit.com/v1/connect/facebook/select-page" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "pending_token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "profile_id": "string", "redirect_url": "https://example.com", "target_ids": [ "string" ] }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## List InstagramAccount targets of a pending connection `GET /connect/instagram/select-account` Targets found after the network sign-in, to render your own picker (headless connect). Pass the pending token as token or the X-Connect-Token header. Access: `write` · MCP tool: `list-instagram-account-connect-targets` · Zernio: `GET /v1/connect/instagram/select-account` ### Query parameters - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) ```bash curl "https://api.socialit.com/v1/connect/instagram/select-account" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true, "account_id": "string", "details": {} } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" } ``` ## Connect the selected InstagramAccount targets `POST /connect/instagram/select-account` Access: `write` · MCP tool: `select-instagram-account-connect-targets` · Zernio: `POST /v1/connect/instagram/select-account` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) - `profile_id` (string) - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme - `target_ids` (array of string; ≤ 500 items) - `account_ids` (array of string; ≤ 500 items) - `page_ids` (array of string; ≤ 500 items) - `page_id` (string; ≤ 100 characters) ```bash curl -X POST "https://api.socialit.com/v1/connect/instagram/select-account" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "pending_token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "profile_id": "string", "redirect_url": "https://example.com", "target_ids": [ "string" ] }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## List LinkedinOrganization targets of a pending connection `GET /connect/linkedin/organizations` Targets found after the network sign-in, to render your own picker (headless connect). Pass the pending token as token or the X-Connect-Token header. Access: `write` · MCP tool: `list-linkedin-organization-connect-targets` · Zernio: `GET /v1/connect/linkedin/organizations` ### Query parameters - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) ```bash curl "https://api.socialit.com/v1/connect/linkedin/organizations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true, "account_id": "string", "details": {} } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" } ``` ## Connect the selected LinkedinOrganization targets `POST /connect/linkedin/select-organization` Access: `write` · MCP tool: `select-linkedin-organization-connect-targets` · Zernio: `POST /v1/connect/linkedin/select-organization` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) - `profile_id` (string) - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme - `target_ids` (array of string; ≤ 500 items) - `organization_ids` (array of string; ≤ 500 items) - `include_personal` (boolean) - `selections` (array of object; ≤ 200 items) - `selections[].account_type` (string; one of personal, organization) - `selections[].organization_id` (string; ≤ 200 characters) ```bash curl -X POST "https://api.socialit.com/v1/connect/linkedin/select-organization" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "pending_token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "profile_id": "string", "redirect_url": "https://example.com", "target_ids": [ "string" ] }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## List PinterestBoard targets of a pending connection `GET /connect/pinterest/select-board` Targets found after the network sign-in, to render your own picker (headless connect). Pass the pending token as token or the X-Connect-Token header. Access: `write` · MCP tool: `list-pinterest-board-connect-targets` · Zernio: `GET /v1/connect/pinterest/select-board` ### Query parameters - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) ```bash curl "https://api.socialit.com/v1/connect/pinterest/select-board" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true, "account_id": "string", "details": {} } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" } ``` ## Connect the selected PinterestBoard targets `POST /connect/pinterest/select-board` Access: `write` · MCP tool: `select-pinterest-board-connect-targets` · Zernio: `POST /v1/connect/pinterest/select-board` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) - `profile_id` (string) - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme - `target_ids` (array of string; ≤ 500 items) - `board_id` (string; required; ≤ 100 characters) - `board_name` (string; ≤ 200 characters) ```bash curl -X POST "https://api.socialit.com/v1/connect/pinterest/select-board" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "pending_token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "profile_id": "string", "redirect_url": "https://example.com", "board_id": "string" }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## List GoogleBusinessLocation targets of a pending connection `GET /connect/googlebusiness/locations` Targets found after the network sign-in, to render your own picker (headless connect). Pass the pending token as token or the X-Connect-Token header. Access: `write` · MCP tool: `list-google-business-location-connect-targets` · Zernio: `GET /v1/connect/googlebusiness/locations` ### Query parameters - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) ```bash curl "https://api.socialit.com/v1/connect/googlebusiness/locations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true, "account_id": "string", "details": {} } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" } ``` ## Connect the selected GoogleBusinessLocation targets `POST /connect/googlebusiness/select-location` Access: `write` · MCP tool: `select-google-business-location-connect-targets` · Zernio: `POST /v1/connect/googlebusiness/select-location` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) - `profile_id` (string) - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme - `target_ids` (array of string; ≤ 500 items) - `location_ids` (array of string; ≤ 500 items) - `location_id` (string; ≤ 200 characters) ```bash curl -X POST "https://api.socialit.com/v1/connect/googlebusiness/select-location" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "pending_token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "profile_id": "string", "redirect_url": "https://example.com", "target_ids": [ "string" ] }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## List SnapchatProfile targets of a pending connection `GET /connect/snapchat/select-profile` Targets found after the network sign-in, to render your own picker (headless connect). Pass the pending token as token or the X-Connect-Token header. Access: `write` · MCP tool: `list-snapchat-profile-connect-targets` · Zernio: `GET /v1/connect/snapchat/select-profile` ### Query parameters - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) ```bash curl "https://api.socialit.com/v1/connect/snapchat/select-profile" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true, "account_id": "string", "details": {} } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" } ``` ## Connect the selected SnapchatProfile targets `POST /connect/snapchat/select-profile` Access: `write` · MCP tool: `select-snapchat-profile-connect-targets` · Zernio: `POST /v1/connect/snapchat/select-profile` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `pending_token` (string; 1–128 characters): Pending connection token (cpt_…) - `profile_id` (string) - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme - `target_ids` (array of string; ≤ 500 items) - `public_profile_id` (string; ≤ 100 characters) ```bash curl -X POST "https://api.socialit.com/v1/connect/snapchat/select-profile" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "pending_token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "profile_id": "string", "redirect_url": "https://example.com", "target_ids": [ "string" ] }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## Connect Bluesky with an app password `POST /connect/bluesky/credentials` Access: `write` · MCP tool: `connect-bluesky-credentials` · Zernio: `POST /v1/connect/bluesky/credentials` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `identifier` (string; required; 1–255 characters) - `app_password` (string; 1–500 characters) - `password` (string; 1–500 characters) - `auth_factor_token` (string; ≤ 100 characters) - `profile_id` (string) - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme - `state` (string; ≤ 200 characters): Ignored (Zernio compatibility) ```bash curl -X POST "https://api.socialit.com/v1/connect/bluesky/credentials" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "identifier": "string", "app_password": "string", "password": "string", "auth_factor_token": "string", "profile_id": "string" }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## Connect Discord channels `POST /connect/discord` Bind channels of a guild where the Socialit bot is installed (or of a pending Discord install token). Access: `write` · MCP tool: `connect-discord-channels` · Zernio: `POST /v1/connect/discord` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `guild_id` (string; ≤ 40 characters) - `channel_id` (string; ≤ 40 characters) - `channel_ids` (array of string; ≤ 25 items) - `profile_id` (string) - `token` (string; 1–128 characters): Pending connection token (cpt_…) - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme ```bash curl -X POST "https://api.socialit.com/v1/connect/discord" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "guild_id": "string", "channel_id": "string", "channel_ids": [ "string" ], "profile_id": "string", "token": "cpt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" }' ``` Response 200: ```json { "object": "connect_result", "status": "connected", "platform": "string", "profile_id": "string", "accounts": [ { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "profile", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "active", "is_active": true, "needs_reconnect": true, "publishing_paused": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "failed": [ { "id": "string", "code": "string", "message": "string" } ], "pending": { "object": "connect_pending", "token": "string", "platform": "string", "flow": "string", "profile_id": "string", "step": "string", "multiple": true, "user_profile": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com" }, "targets": [ { "id": "string", "account_type": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "already_connected": true } ], "options": [ { "id": "string", "name": "string", "description": "string", "privacy": "string" } ], "expires_at": "2026-10-13T09:00:00.000Z" }, "redirect_url": "https://example.com" } ``` ## List hosted connect links `GET /connect/links` Access: `admin` · MCP tool: `list-connect-links` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, expires_at, name) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string) - `status` (string; one of active, expired, revoked, exhausted) ```bash curl "https://api.socialit.com/v1/connect/links" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "connect_link", "id": "string", "name": "string", "profile_id": "string", "url": "https://example.com", "platforms": [ "string" ], "branding": { "name": "string", "logo_url": "https://example.com", "primary_color": "string", "accent_color": "string", "background_color": "string" }, "redirect_url": "https://example.com", "status": "active", "max_uses": 1, "use_count": 1, "last_used_at": "2026-10-13T09:00:00.000Z", "expires_at": "2026-10-13T09:00:00.000Z", "revoked_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a hosted connect link `POST /connect/links` A branded page where your customer connects their accounts to one profile, then lands on redirect_url with account_ids. Access: `admin` · MCP tool: `create-connect-link` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string; required) - `name` (string | null; ≤ 100 characters) - `platforms` (array of string | null; ≤ 40 items) - `branding` (object) - `branding.name` (string | null; ≤ 60 characters) - `branding.logo_url` (string | null; ≤ 1000 characters) - `branding.primary_color` (string | null; pattern ^#[0-9A-Fa-f]{6}$): Hex color #RRGGBB - `branding.accent_color` (string | null; pattern ^#[0-9A-Fa-f]{6}$): Hex color #RRGGBB - `branding.background_color` (string | null; pattern ^#[0-9A-Fa-f]{6}$): Hex color #RRGGBB - `redirect_url` (string | null; ≤ 2000 characters): Absolute http(s) URL or app scheme - `expires_in` (integer; 300–2592000) - `expires_at` (string (date-time)) - `max_uses` (integer | null; 1–10000) ```bash curl -X POST "https://api.socialit.com/v1/connect/links" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "name": "string", "platforms": [ "string" ], "branding": { "name": "string", "logo_url": "https://example.com" }, "redirect_url": "https://example.com" }' ``` Response 201: ```json { "object": "connect_link", "id": "string", "name": "string", "profile_id": "string", "url": "https://example.com", "platforms": [ "string" ], "branding": { "name": "string", "logo_url": "https://example.com", "primary_color": "string", "accent_color": "string", "background_color": "string" }, "redirect_url": "https://example.com", "status": "active", "max_uses": 1, "use_count": 1, "last_used_at": "2026-10-13T09:00:00.000Z", "expires_at": "2026-10-13T09:00:00.000Z", "revoked_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get a hosted connect link `GET /connect/links/{id}` Access: `admin` · MCP tool: `get-connect-link` ### Path parameters - `id` (string; required; 1–80 characters): connectLink id (cl_…) ```bash curl "https://api.socialit.com/v1/connect/links/cl_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connect_link", "id": "string", "name": "string", "profile_id": "string", "url": "https://example.com", "platforms": [ "string" ], "branding": { "name": "string", "logo_url": "https://example.com", "primary_color": "string", "accent_color": "string", "background_color": "string" }, "redirect_url": "https://example.com", "status": "active", "max_uses": 1, "use_count": 1, "last_used_at": "2026-10-13T09:00:00.000Z", "expires_at": "2026-10-13T09:00:00.000Z", "revoked_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Revoke a hosted connect link `DELETE /connect/links/{id}` Access: `admin` · MCP tool: `revoke-connect-link` ### Path parameters - `id` (string; required; 1–80 characters): connectLink id (cl_…) ```bash curl -X DELETE "https://api.socialit.com/v1/connect/links/cl_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connect_link", "id": "string", "deleted": true } ``` --- Source: https://socialit.com/docs/api-reference/accounts/ # API Keys API > Workspace API keys. Keys are stored hashed; the secret is shown once. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## Verify the current credential `GET /auth/verify` Returns the workspace, permission and scopes of the API key or OAuth token used. Access: `read` · MCP tool: `verify-credential` · Zernio: `GET /v1/auth/verify` ```bash curl "https://api.socialit.com/v1/auth/verify" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "credential", "type": "api_key", "workspace": { "id": "string", "name": "string" }, "permission": "full", "scopes": [ "string" ], "api_key_id": "string", "client_id": "string", "user_id": "string", "profile_ids": [ "string" ] } ``` ## List API keys `GET /api-keys` Access: `admin` · MCP tool: `list-api-keys` · Zernio: `GET /v1/api-keys` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, last_used_at, name) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `name` (string) ```bash curl "https://api.socialit.com/v1/api-keys" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "api_key", "id": "string", "name": "string", "permission": "full", "profile_ids": [ "string" ], "prefix": "string", "key": "string", "last_used_at": "2026-10-13T09:00:00.000Z", "expires_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create an API key `POST /api-keys` The response contains the secret key. It is never shown again. Access: `admin` · MCP tool: `create-api-key` · Zernio: `POST /v1/api-keys` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–100 characters) - `permission` (string; one of full, read) - `profile_ids` (array of string | null; ≤ 500 items): Restrict the key to these profiles (null = all) - `expires_at` (string (date-time) | null) - `expires_in_days` (integer; 1–3650): Alternative to expires_at ```bash curl -X POST "https://api.socialit.com/v1/api-keys" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "permission": "full", "profile_ids": [ "string" ], "expires_at": "2026-10-13T09:00:00.000Z", "expires_in_days": 1 }' ``` Response 201: ```json { "object": "api_key", "id": "string", "name": "string", "permission": "full", "profile_ids": [ "string" ], "prefix": "string", "key": "string", "last_used_at": "2026-10-13T09:00:00.000Z", "expires_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z" } ``` ## Get an API key `GET /api-keys/{id}` Access: `admin` · MCP tool: `get-api-key` ### Path parameters - `id` (string; required; 1–80 characters): apiKey id (key_…) ```bash curl "https://api.socialit.com/v1/api-keys/key_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "api_key", "id": "string", "name": "string", "permission": "full", "profile_ids": [ "string" ], "prefix": "string", "key": "string", "last_used_at": "2026-10-13T09:00:00.000Z", "expires_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z" } ``` ## Update an API key `PATCH /api-keys/{id}` Access: `admin` · MCP tool: `update-api-key` ### Path parameters - `id` (string; required; 1–80 characters): apiKey id (key_…) ### Body - `name` (string; 1–100 characters) - `permission` (string; one of full, read) - `profile_ids` (array of string | null; ≤ 500 items): Restrict the key to these profiles (null = all) - `expires_at` (string (date-time) | null) ```bash curl -X PATCH "https://api.socialit.com/v1/api-keys/key_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "permission": "full", "profile_ids": [ "string" ], "expires_at": "2026-10-13T09:00:00.000Z" }' ``` Response 200: ```json { "object": "api_key", "id": "string", "name": "string", "permission": "full", "profile_ids": [ "string" ], "prefix": "string", "key": "string", "last_used_at": "2026-10-13T09:00:00.000Z", "expires_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete an API key `DELETE /api-keys/{id}` Revokes the key immediately. Access: `admin` · MCP tool: `delete-api-key` · Zernio: `DELETE /v1/api-keys/{keyId}` ### Path parameters - `id` (string; required; 1–80 characters): apiKey id (key_…) ```bash curl -X DELETE "https://api.socialit.com/v1/api-keys/key_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "api_key", "id": "string", "deleted": true } ``` ## Regenerate an API key `POST /api-keys/{id}/regenerate` Issues a new secret for the same key; the old secret stops working. Access: `admin` · MCP tool: `regenerate-api-key` ### Path parameters - `id` (string; required; 1–80 characters): apiKey id (key_…) ```bash curl -X POST "https://api.socialit.com/v1/api-keys/key_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/regenerate" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "api_key", "id": "string", "name": "string", "permission": "full", "profile_ids": [ "string" ], "prefix": "string", "key": "string", "last_used_at": "2026-10-13T09:00:00.000Z", "expires_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z" } ``` --- Source: https://socialit.com/docs/api-reference/api-keys/ # Webhooks API > Signed HTTPS callbacks for workspace events. Each delivery carries X-Socialit-Signature (hex HMAC-SHA256 of ${timestamp}.${body} with the webhook secret) and X-Socialit-Timestamp. Failed deliveries retry after 5m, 30m, 2h, 5h, then every 12h (11 attempts); a webhook failing for 3 days is disabled. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List webhooks `GET /webhooks` Access: `admin` · MCP tool: `list-webhooks` · Zernio: `GET /v1/webhooks/settings` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name, last_delivery_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `enabled` (string) ```bash curl "https://api.socialit.com/v1/webhooks" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "webhook", "id": "string", "name": "string", "url": "https://example.com", "enabled": true, "all_events": true, "events": [ "string" ], "profile_ids": [ "string" ], "secret": "string", "last_delivery_at": "2026-10-13T09:00:00.000Z", "failure_count": 1, "disabled_reason": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a webhook `POST /webhooks` The response contains the signing secret; it is only shown again after reset-secret. Access: `admin` · MCP tool: `create-webhook` · Zernio: `POST /v1/webhooks/settings` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–100 characters) - `url` (string; required; 8–2048 characters) - `events` (array of string; ≤ 200 items, unique) - `all_events` (boolean) - `profile_ids` (array of string | null; ≤ 500 items) - `enabled` (boolean) - `secret` (string; 16–256 characters): Bring your own signing secret (default: generated) ```bash curl -X POST "https://api.socialit.com/v1/webhooks" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "url": "https://example.com", "events": [ "*" ], "all_events": true, "profile_ids": [ "string" ] }' ``` Response 201: ```json { "object": "webhook", "id": "string", "name": "string", "url": "https://example.com", "enabled": true, "all_events": true, "events": [ "string" ], "profile_ids": [ "string" ], "secret": "string", "last_delivery_at": "2026-10-13T09:00:00.000Z", "failure_count": 1, "disabled_reason": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get a webhook `GET /webhooks/{id}` Access: `admin` · MCP tool: `get-webhook` ### Path parameters - `id` (string; required; 1–80 characters): webhook id (wh_…) ```bash curl "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "webhook", "id": "string", "name": "string", "url": "https://example.com", "enabled": true, "all_events": true, "events": [ "string" ], "profile_ids": [ "string" ], "secret": "string", "last_delivery_at": "2026-10-13T09:00:00.000Z", "failure_count": 1, "disabled_reason": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a webhook `PATCH /webhooks/{id}` Re-enabling a disabled webhook resets its failure streak. Access: `admin` · MCP tool: `update-webhook` · Zernio: `PUT /v1/webhooks/settings` ### Path parameters - `id` (string; required; 1–80 characters): webhook id (wh_…) ### Body - `name` (string; 1–100 characters) - `url` (string; 8–2048 characters) - `events` (array of string; ≤ 200 items, unique) - `all_events` (boolean) - `profile_ids` (array of string | null; ≤ 500 items) - `enabled` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "url": "https://example.com", "events": [ "*" ], "all_events": true, "profile_ids": [ "string" ] }' ``` Response 200: ```json { "object": "webhook", "id": "string", "name": "string", "url": "https://example.com", "enabled": true, "all_events": true, "events": [ "string" ], "profile_ids": [ "string" ], "secret": "string", "last_delivery_at": "2026-10-13T09:00:00.000Z", "failure_count": 1, "disabled_reason": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a webhook `DELETE /webhooks/{id}` Access: `admin` · MCP tool: `delete-webhook` · Zernio: `DELETE /v1/webhooks/settings` ### Path parameters - `id` (string; required; 1–80 characters): webhook id (wh_…) ```bash curl -X DELETE "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "webhook", "id": "string", "deleted": true } ``` ## Send a test event `POST /webhooks/{id}/test` Sends one signed sample event now and returns the receiver response. Not retried. Access: `admin` · MCP tool: `test-webhook` · Zernio: `POST /v1/webhooks/test` ### Path parameters - `id` (string; required; 1–80 characters): webhook id (wh_…) ### Body - `type` (string; one of post.scheduled, post.publishing, post.published, post.partially_published, post.failed, post.deleted, post.unpublished, post.cancelled, post.edited, post.recycled, post.approval_requested, post.approved, …): Sample event type (default webhook.test) ```bash curl -X POST "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/test" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "post.scheduled" }' ``` Response 200: ```json { "object": "webhook_test", "success": true, "status_code": 1, "duration_ms": 1, "response_body": "string", "error": "string", "delivery": { "object": "webhook_delivery", "id": "string", "webhook_id": "string", "event_id": "string", "event_type": "string", "attempt": 1, "status": "pending", "status_code": 1, "response_body": "string", "error": "string", "duration_ms": 1, "test": true, "next_retry_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z" } } ``` ## Rotate the signing secret `POST /webhooks/{id}/reset-secret` Access: `admin` · MCP tool: `reset-webhook-secret` ### Path parameters - `id` (string; required; 1–80 characters): webhook id (wh_…) ```bash curl -X POST "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reset-secret" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "webhook", "id": "string", "name": "string", "url": "https://example.com", "enabled": true, "all_events": true, "events": [ "string" ], "profile_ids": [ "string" ], "secret": "string", "last_delivery_at": "2026-10-13T09:00:00.000Z", "failure_count": 1, "disabled_reason": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List webhook deliveries `GET /webhooks/deliveries` Delivery log across every webhook of the workspace. Access: `admin` · MCP tool: `list-all-webhook-deliveries` · Zernio: `GET /v1/webhooks/logs` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, status_code, attempt) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `status` (string) - `event_type` (string) - `webhook_id` (string) - `event_id` (string) ```bash curl "https://api.socialit.com/v1/webhooks/deliveries" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "webhook_delivery", "id": "string", "webhook_id": "string", "event_id": "string", "event_type": "string", "attempt": 1, "status": "pending", "status_code": 1, "response_body": "string", "error": "string", "duration_ms": 1, "test": true, "next_retry_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a webhook delivery `GET /webhooks/deliveries/{id}` Access: `admin` · MCP tool: `get-webhook-delivery` ### Path parameters - `id` (string; required; 1–80 characters): webhookDelivery id (whd_…) ```bash curl "https://api.socialit.com/v1/webhooks/deliveries/whd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "webhook_delivery", "id": "string", "webhook_id": "string", "event_id": "string", "event_type": "string", "attempt": 1, "status": "pending", "status_code": 1, "response_body": "string", "error": "string", "duration_ms": 1, "test": true, "next_retry_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z" } ``` ## Redeliver an event `POST /webhooks/deliveries/{id}/redeliver` Queues a new delivery of the same event to the same webhook. Access: `admin` · MCP tool: `redeliver-webhook-delivery` · Zernio: `POST /v1/webhooks/logs/redeliver` ### Path parameters - `id` (string; required; 1–80 characters): webhookDelivery id (whd_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/webhooks/deliveries/whd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/redeliver" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 201: ```json { "object": "webhook_delivery", "id": "string", "webhook_id": "string", "event_id": "string", "event_type": "string", "attempt": 1, "status": "pending", "status_code": 1, "response_body": "string", "error": "string", "duration_ms": 1, "test": true, "next_retry_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z" } ``` ## List a webhook's deliveries `GET /webhooks/{id}/deliveries` Access: `admin` · MCP tool: `list-webhook-deliveries` ### Path parameters - `id` (string; required; 1–80 characters): webhook id (wh_…) ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, status_code, attempt) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `status` (string) - `event_type` (string) - `webhook_id` (string) - `event_id` (string) ```bash curl "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/deliveries" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "webhook_delivery", "id": "string", "webhook_id": "string", "event_id": "string", "event_type": "string", "attempt": 1, "status": "pending", "status_code": 1, "response_body": "string", "error": "string", "duration_ms": 1, "test": true, "next_retry_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Retry failed deliveries `POST /webhooks/{id}/retry-failed` Re-queues failed deliveries from the last 3 days. Access: `admin` · MCP tool: `retry-failed-webhook-deliveries` ### Path parameters - `id` (string; required; 1–80 characters): webhook id (wh_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/webhooks/wh_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/retry-failed" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 200: ```json { "object": "webhook_retry", "webhook_id": "string", "retried": 1 } ``` --- Source: https://socialit.com/docs/api-reference/webhooks/ # Events API > The workspace event log (the payloads webhooks receive) and the event type catalog. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List event types `GET /events/names` Every event type a webhook can subscribe to, with its group and description. Access: `read` · MCP tool: `list-event-types` ```bash curl "https://api.socialit.com/v1/events/names" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "event_type", "type": "string", "group": "string", "description": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## List events `GET /events` Access: `read` · MCP tool: `list-events` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `type` (string) - `profile_id` (string) ```bash curl "https://api.socialit.com/v1/events" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "event", "id": "string", "type": "string", "profile_id": "string", "data": {}, "created_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get an event `GET /events/{id}` Access: `read` · MCP tool: `get-event` ### Path parameters - `id` (string; required; 1–80 characters): event id (evt_…) ```bash curl "https://api.socialit.com/v1/events/evt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "event", "id": "string", "type": "string", "profile_id": "string", "data": {}, "created_at": "2026-10-13T09:00:00.000Z" } ``` --- Source: https://socialit.com/docs/api-reference/events/ # Logs API > API request logs (public API + MCP) and the workspace activity log. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List API request logs `GET /logs` Filter with status, method, path, api_key_id, source, created_at.after / created_at.before, or any .. Access: `admin` · MCP tool: `list-request-logs` · Zernio: `GET /v1/logs` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, status, duration_ms) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `status` (string) - `method` (string) - `path` (string) - `api_key_id` (string) - `source` (string) ```bash curl "https://api.socialit.com/v1/logs" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "request_log", "id": "string", "method": "string", "path": "string", "route": "string", "operation_id": "string", "source": "api", "status": 1, "duration_ms": 1, "api_key_id": "string", "oauth_client_id": "string", "request_id": "string", "ip": "string", "user_agent": "string", "request_body": {}, "response_body": {}, "created_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get an API request log `GET /logs/{id}` Includes the (redacted) request and response bodies. Access: `admin` · MCP tool: `get-request-log` ### Path parameters - `id` (string; required; 1–80 characters): requestLog id (log_…) ```bash curl "https://api.socialit.com/v1/logs/log_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "request_log", "id": "string", "method": "string", "path": "string", "route": "string", "operation_id": "string", "source": "api", "status": 1, "duration_ms": 1, "api_key_id": "string", "oauth_client_id": "string", "request_id": "string", "ip": "string", "user_agent": "string", "request_body": {}, "response_body": {}, "created_at": "2026-10-13T09:00:00.000Z" } ``` ## List workspace activity `GET /activity` Audit log of changes to workspace settings, members, API keys and webhooks. Access: `admin` · MCP tool: `list-activity` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `action` (string) - `actor_type` (string) - `target_type` (string) ```bash curl "https://api.socialit.com/v1/activity" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "activity", "id": "string", "actor": { "type": "string", "id": "string", "name": "string" }, "action": "string", "target": { "type": "string", "id": "string", "name": "string" }, "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` --- Source: https://socialit.com/docs/api-reference/logs/ # Invitations API > Email invitations, invite codes and invite links. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## Create an invite link `POST /invite/tokens` A shareable link that adds whoever opens it (after sign-in) to this workspace with the given role and profile access. Access: `admin` · MCP tool: `create-invite-token` · Zernio: `POST /v1/invite/tokens` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `role` (string; one of admin, member, billing, viewer) - `profile_ids` (array of string; ≤ 500 items) - `scope` (string; one of all, profiles): Zernio compatibility: profiles requires profile_ids - `expires_in` (integer; 300–2592000): Seconds until the link expires (default 7 days, max 30) ```bash curl -X POST "https://api.socialit.com/v1/invite/tokens" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "role": "member", "profile_ids": [ "string" ], "scope": "all", "expires_in": 604800 }' ``` Response 201: ```json { "object": "invite_token", "token": "string", "url": "https://example.com", "role": "admin", "profile_ids": [ "string" ], "expires_at": "2026-10-13T09:00:00.000Z" } ``` --- Source: https://socialit.com/docs/api-reference/invitations/ # Users API > People with access to the workspace. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List users `GET /users` Workspace members with their role and profile access. Access: `read` · MCP tool: `list-users` · Zernio: `GET /v1/users` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, email, name, role) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `role` (string) - `email` (string) ```bash curl "https://api.socialit.com/v1/users" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "user", "id": "string", "name": "string", "email": "you@example.com", "avatar_url": "https://example.com", "role": "owner", "all_profiles": true, "profile_ids": [ "string" ], "joined_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a user `GET /users/{id}` Access: `read` · MCP tool: `get-user` · Zernio: `GET /v1/users/{userId}` ### Path parameters - `id` (string; required): User id (usr_…) ```bash curl "https://api.socialit.com/v1/users/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "user", "id": "string", "name": "string", "email": "you@example.com", "avatar_url": "https://example.com", "role": "owner", "all_profiles": true, "profile_ids": [ "string" ], "joined_at": "2026-10-13T09:00:00.000Z" } ``` --- Source: https://socialit.com/docs/api-reference/users/ # Posts API > Create, schedule and publish posts to connected accounts; track per-account results. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List posts `GET /posts` Posts with their per-account postings. Filters: status (repeatable), profile_id, account_id, platform, queue_id, tag, search, created_by, from/to on date_field, recycling. Access: `read` · MCP tool: `list-posts` · Zernio: `GET /v1/posts` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, scheduled_at, published_at, status, updated_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `status` (array of string): Status (repeatable or comma-separated): draft, pending_approval, scheduled, publishing, published, partially_published, failed, cancelled - `profile_id` (string) - `account_id` (string) - `platform` (string) - `queue_id` (string) - `tag` (string) - `search` (string; ≤ 200 characters) - `created_by` (string) - `from` (string (date-time)) - `to` (string (date-time)) - `date_field` (string; one of scheduled_at, created_at, published_at) - `recycling` (boolean) ```bash curl "https://api.socialit.com/v1/posts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string" } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a post `POST /posts` Create a draft, schedule it (scheduled_at + timezone), take the next queue slot (queue / queue_id) or publish now (publish_now). Targets: account_ids, targets (per-account overrides), profile_id or group_id (filtered by platforms). Network options go in platform_options. (see GET /posts/platform-options). With workspace approvals on, members create posts in pending_approval. Access: `write` · MCP tool: `create-post` · Zernio: `POST /v1/posts` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `content` (string; ≤ 63206 characters) - `title` (string | null; ≤ 300 characters) - `account_ids` (array of string; ≤ 200 items) - `profile_id` (string | null; ≤ 80 characters) - `group_id` (string; ≤ 80 characters) - `platforms` (array of string; ≤ 30 items) - `targets` (array of object; ≤ 200 items) - `targets[].account_id` (string; required; 1–80 characters): socialAccount id (sa_…) - `targets[].content` (string; ≤ 63206 characters) - `targets[].media_ids` (array of string; ≤ 35 items) - `targets[].media_urls` (array of any; ≤ 35 items): Public HTTPS URLs or { url, alt_text?, type? } - `targets[].media` (array of object; ≤ 35 items) - `targets[].media[].media_id` (string; 1–80 characters): media id (med_…) - `targets[].media[].url` (string; ≤ 2048 characters) - `targets[].media[].alt_text` (string; ≤ 2000 characters) - `targets[].media[].type` (string; one of image, video, gif, document) - `targets[].platform_options` (object) - `targets[].first_comment` (string; ≤ 10000 characters) - `targets[].scheduled_at` (string; ≤ 40 characters) - `media_ids` (array of string; ≤ 35 items) - `media_urls` (array of any; ≤ 35 items): Public HTTPS URLs or { url, alt_text?, type? } - `media` (array of object; ≤ 35 items) - `media[].media_id` (string; 1–80 characters): media id (med_…) - `media[].url` (string; ≤ 2048 characters) - `media[].alt_text` (string; ≤ 2000 characters) - `media[].type` (string; one of image, video, gif, document) - `platform_options` (object) - `first_comment` (string | null; ≤ 10000 characters) - `thread_items` (array of object; ≤ 25 items) - `thread_items[].content` (string; required; ≤ 63206 characters) - `thread_items[].media_ids` (array of string; ≤ 10 items) - `quote_post_id` (string | null; ≤ 80 characters) - `quote_url` (string | null; ≤ 2048 characters) - `reply_to_url` (string | null; ≤ 2048 characters) - `scheduled_at` (string | null; ≤ 40 characters): ISO 8601; without offset = wall clock in timezone - `timezone` (string | null; ≤ 64 characters) - `publish_now` (boolean) - `queue` (boolean) - `queue_id` (string | null; ≤ 80 characters) - `draft` (boolean) - `tags` (array of string; ≤ 50 items) - `metadata` (object) - `strict` (boolean) - `recycle` (object | null) - `recycle.enabled` (boolean; required) - `recycle.interval` (integer; 1–365) - `recycle.interval_unit` (string; one of day, week, month) - `recycle.start_at` (string (date-time)) - `recycle.max_count` (integer | null; 1–1000) - `recycle.expires_at` (string (date-time) | null) - `recycle.content_variations` (array of string; ≤ 20 items) - `note` (string; ≤ 5000 characters) ```bash curl -X POST "https://api.socialit.com/v1/posts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "content": "string", "title": "string", "account_ids": [ "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ], "profile_id": "string", "group_id": "string" }' ``` Response 201: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Publish option schemas per network `GET /posts/platform-options` JSON schema of platform_options. for every network, from each network adapter. Access: `read` · MCP tool: `get-post-platform-options` ```bash curl "https://api.socialit.com/v1/posts/platform-options" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "platform_options_schemas", "data": { "key": {} } } ``` ## Bulk create posts from CSV `POST /posts/bulk-upload` multipart/form-data file (CSV, ≤ 5,000 rows, ≤ 10 MB) or JSON { csv }. ?dry_run=true validates only. Columns: accounts, profile, platforms, content, title, media_urls, scheduled_at, timezone, publish_now, queue, queue_id, draft, first_comment, tags, content_, media_urls_, scheduled_at_ (Zernio aliases accepted). Access: `write` · MCP tool: `bulk-upload-posts` · Zernio: `POST /v1/posts/bulk-upload` ### Query parameters - `dry_run` (boolean) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `csv` (string) ```bash curl -X POST "https://api.socialit.com/v1/posts/bulk-upload" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "csv": "string" }' ``` Response 200: ```json { "object": "bulk_upload", "dry_run": true, "total": 1, "valid": 1, "invalid": 1, "created": 1, "warnings": [ "string" ], "results": [ { "row": 1, "valid": true, "post_id": "string", "status": "string", "errors": [ "string" ], "warnings": [ "string" ] } ] } ``` ## Get a post `GET /posts/{id}` Access: `read` · MCP tool: `get-post` · Zernio: `GET /v1/posts/{postId}` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ```bash curl "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a post `PATCH /posts/{id}` Drafts, pending, scheduled, failed, partially published and cancelled posts. Published posts only accept recycle, tags, metadata and title. Targets/media sent replace the current ones. Access: `write` · MCP tool: `update-post` · Zernio: `PUT /v1/posts/{postId}` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Body - `content` (string; ≤ 63206 characters) - `title` (string | null; ≤ 300 characters) - `account_ids` (array of string; ≤ 200 items) - `profile_id` (string | null; ≤ 80 characters) - `group_id` (string; ≤ 80 characters) - `platforms` (array of string; ≤ 30 items) - `targets` (array of object; ≤ 200 items) - `targets[].account_id` (string; required; 1–80 characters): socialAccount id (sa_…) - `targets[].content` (string; ≤ 63206 characters) - `targets[].media_ids` (array of string; ≤ 35 items) - `targets[].media_urls` (array of any; ≤ 35 items): Public HTTPS URLs or { url, alt_text?, type? } - `targets[].media` (array of object; ≤ 35 items) - `targets[].media[].media_id` (string; 1–80 characters): media id (med_…) - `targets[].media[].url` (string; ≤ 2048 characters) - `targets[].media[].alt_text` (string; ≤ 2000 characters) - `targets[].media[].type` (string; one of image, video, gif, document) - `targets[].platform_options` (object) - `targets[].first_comment` (string; ≤ 10000 characters) - `targets[].scheduled_at` (string; ≤ 40 characters) - `media_ids` (array of string; ≤ 35 items) - `media_urls` (array of any; ≤ 35 items): Public HTTPS URLs or { url, alt_text?, type? } - `media` (array of object; ≤ 35 items) - `media[].media_id` (string; 1–80 characters): media id (med_…) - `media[].url` (string; ≤ 2048 characters) - `media[].alt_text` (string; ≤ 2000 characters) - `media[].type` (string; one of image, video, gif, document) - `platform_options` (object) - `first_comment` (string | null; ≤ 10000 characters) - `thread_items` (array of object; ≤ 25 items) - `thread_items[].content` (string; required; ≤ 63206 characters) - `thread_items[].media_ids` (array of string; ≤ 10 items) - `quote_post_id` (string | null; ≤ 80 characters) - `quote_url` (string | null; ≤ 2048 characters) - `reply_to_url` (string | null; ≤ 2048 characters) - `scheduled_at` (string | null; ≤ 40 characters): ISO 8601; without offset = wall clock in timezone - `timezone` (string | null; ≤ 64 characters) - `publish_now` (boolean) - `queue` (boolean) - `queue_id` (string | null; ≤ 80 characters) - `draft` (boolean) - `tags` (array of string; ≤ 50 items) - `metadata` (object) - `strict` (boolean) - `recycle` (object | null) - `recycle.enabled` (boolean; required) - `recycle.interval` (integer; 1–365) - `recycle.interval_unit` (string; one of day, week, month) - `recycle.start_at` (string (date-time)) - `recycle.max_count` (integer | null; 1–1000) - `recycle.expires_at` (string (date-time) | null) - `recycle.content_variations` (array of string; ≤ 20 items) - `note` (string; ≤ 5000 characters) - `schedule` (boolean): Schedule a draft at scheduled_at ```bash curl -X PATCH "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "string", "title": "string", "account_ids": [ "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ], "profile_id": "string", "group_id": "string" }' ``` Response 200: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a post `DELETE /posts/{id}` delete_on_network=true also deletes the published copies on the networks (failures are returned as warnings). Access: `write` · MCP tool: `delete-post` · Zernio: `DELETE /v1/posts/{postId}` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Query parameters - `delete_on_network` (boolean) ```bash curl -X DELETE "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "post", "id": "string", "deleted": true, "warnings": [ "string" ] } ``` ## Schedule, queue or publish a draft `POST /posts/{id}/schedule` Access: `write` · MCP tool: `schedule-post` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `scheduled_at` (string | null; ≤ 40 characters): ISO 8601; without offset = wall clock in timezone - `timezone` (string | null; ≤ 64 characters) - `publish_now` (boolean) - `queue` (boolean) - `queue_id` (string | null; ≤ 80 characters) ```bash curl -X POST "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/schedule" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "publish_now": true, "queue": true, "queue_id": "string" }' ``` Response 200: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Cancel a scheduled post `POST /posts/{id}/cancel` Access: `write` · MCP tool: `cancel-post` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ```bash curl -X POST "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/cancel" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Retry failed postings `POST /posts/{id}/retry` Re-publish the failed postings of a failed or partially published post (optionally only account_ids). Access: `write` · MCP tool: `retry-post` · Zernio: `POST /v1/posts/{postId}/retry` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_ids` (array of string) ```bash curl -X POST "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/retry" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_ids": [ "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ] }' ``` Response 200: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a published post on the networks `POST /posts/{id}/unpublish` Delete the live post on one account (account_id / platform) or every published account. Access: `write` · MCP tool: `unpublish-post` · Zernio: `POST /v1/posts/{postId}/unpublish` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string; 1–80 characters): socialAccount id (sa_…) - `platform` (string; 1–40 characters): Platform (facebook, instagram, x, linkedin, threads, bluesky, pinterest, tiktok, youtube, google_business, reddit, snapchat, discord, mastodon; aliases twitter, googlebusiness, meta) ```bash curl -X POST "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/unpublish" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform": "string" }' ``` Response 200: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Edit a published post on the network `POST /posts/{id}/edit` Access: `write` · MCP tool: `edit-published-post` · Zernio: `POST /v1/posts/{postId}/edit` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string; 1–80 characters): socialAccount id (sa_…) - `platform` (string; 1–40 characters): Platform (facebook, instagram, x, linkedin, threads, bluesky, pinterest, tiktok, youtube, google_business, reddit, snapchat, discord, mastodon; aliases twitter, googlebusiness, meta) - `content` (string; required; 1–63206 characters) - `media_ids` (array of string; ≤ 35 items) ```bash curl -X POST "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/edit" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform": "string", "content": "string", "media_ids": [ "med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ] }' ``` Response 200: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update video metadata (YouTube) `POST /posts/{id}/update-metadata` Title, description, tags, category, privacy, scheduled publish time, thumbnail and playlist of a YouTube video published by this post (or any video_id of the account). Access: `write` · MCP tool: `update-post-metadata` · Zernio: `POST /v1/posts/{postId}/update-metadata` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string; 1–80 characters): socialAccount id (sa_…) - `platform` (string; 1–40 characters): Platform (facebook, instagram, x, linkedin, threads, bluesky, pinterest, tiktok, youtube, google_business, reddit, snapchat, discord, mastodon; aliases twitter, googlebusiness, meta) - `video_id` (string; ≤ 64 characters) - `title` (string; ≤ 100 characters) - `description` (string; ≤ 5000 characters) - `tags` (array of string; ≤ 500 items) - `category_id` (string; ≤ 10 characters) - `privacy_status` (string; one of public, unlisted, private) - `publish_at` (string (date-time)) - `thumbnail_url` (string; ≤ 2048 characters) - `made_for_kids` (boolean) - `contains_synthetic_media` (boolean) - `playlist_id` (string; ≤ 64 characters) - `license` (string; one of youtube, creativeCommon) - `embeddable` (boolean) - `public_stats_viewable` (boolean) - `default_language` (string; ≤ 20 characters) ```bash curl -X POST "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/update-metadata" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform": "string", "video_id": "string", "title": "string", "description": "string" }' ``` Response 200: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Duplicate a post `POST /posts/{id}/duplicate` Access: `write` · MCP tool: `duplicate-post` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `scheduled_at` (string; ≤ 40 characters) - `account_ids` (array of string) ```bash curl -X POST "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/duplicate" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "scheduled_at": "2026-10-13T09:00:00.000Z", "account_ids": [ "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ] }' ``` Response 201: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Approve a pending post `POST /posts/{id}/approve` Owners, admins and the approvers in publishing settings. Runs the requested action (schedule, publish now or queue). Access: `write` · MCP tool: `approve-post` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `comment` (string; ≤ 5000 characters) ```bash curl -X POST "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/approve" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "comment": "string" }' ``` Response 200: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Reject a pending post `POST /posts/{id}/reject` Access: `write` · MCP tool: `reject-post` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `comment` (string; ≤ 5000 characters) - `reason` (string; ≤ 500 characters) ```bash curl -X POST "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reject" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "comment": "string", "reason": "string" }' ``` Response 200: ```json { "object": "post", "id": "string", "status": "draft", "content": "string", "title": "string", "profile_id": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "mime_type": "string", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "position": 1 } ], "postings": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "platform_options": {}, "first_comment": "string", "thread_items": [ { "content": "string", "media_ids": [ "string" ] } ], "quote_post_id": "string", "quote_url": "https://example.com", "reply_to_url": "https://example.com", "scheduled_at": "2026-10-13T09:00:00.000Z", "timezone": "Europe/Prague", "published_at": "2026-10-13T09:00:00.000Z", "queue_id": "string", "tags": [ "string" ], "metadata": {}, "strict": true, "recycle": { "enabled": true, "interval": 1, "interval_unit": "string", "start_at": "2026-10-13T09:00:00.000Z", "max_count": 1, "expires_at": "2026-10-13T09:00:00.000Z", "content_variations": [ "string" ], "count": 1, "next_at": "2026-10-13T09:00:00.000Z", "last_at": "2026-10-13T09:00:00.000Z" }, "recycled_from_post_id": "string", "approval": { "status": "pending", "requested_by": { "type": "string", "id": "string", "name": "string" }, "requested_at": "2026-10-13T09:00:00.000Z", "decided_by": { "type": "string", "id": "string", "name": "string" }, "decided_at": "2026-10-13T09:00:00.000Z", "comment": "string", "requested_action": "string" }, "error": "string", "warnings": [ "string" ], "notes_count": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List internal notes of a post `GET /posts/{id}/notes` Access: `read` · MCP tool: `list-post-notes` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ```bash curl "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/notes" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "post_note", "id": "string", "post_id": "string", "kind": "note", "body": "string", "author": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Add an internal note to a post `POST /posts/{id}/notes` Access: `write` · MCP tool: `create-post-note` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `body` (string; required; 1–5000 characters) ```bash curl -X POST "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/notes" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "body": "string" }' ``` Response 201: ```json { "object": "post_note", "id": "string", "post_id": "string", "kind": "note", "body": "string", "author": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Edit a post note `PATCH /posts/{id}/notes/{noteId}` Access: `write` · MCP tool: `update-post-note` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) - `noteId` (string; required; 1–80 characters): postNote id (pnt_…) ### Body - `body` (string; required; 1–5000 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/notes/pnt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "body": "string" }' ``` Response 200: ```json { "object": "post_note", "id": "string", "post_id": "string", "kind": "note", "body": "string", "author": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a post note `DELETE /posts/{id}/notes/{noteId}` Access: `write` · MCP tool: `delete-post-note` ### Path parameters - `id` (string; required; 1–80 characters): post id (pst_…) - `noteId` (string; required; 1–80 characters): postNote id (pnt_…) ```bash curl -X DELETE "https://api.socialit.com/v1/posts/pst_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/notes/pnt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "post_note", "id": "string", "deleted": true } ``` ## List postings `GET /postings` One row per post × account with its publish status, network id, URL and error. Access: `read` · MCP tool: `list-postings` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, published_at, updated_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `status` (string; one of pending, processing, published, failed, cancelled) - `post_id` (string) - `account_id` (string) - `platform` (string) ```bash curl "https://api.socialit.com/v1/postings" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a posting `GET /postings/{id}` Access: `read` · MCP tool: `get-posting` ### Path parameters - `id` (string; required; 1–80 characters): socialPosting id (sp_…) ```bash curl "https://api.socialit.com/v1/postings/sp_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "posting", "id": "string", "post_id": "string", "account_id": "string", "platform": "string", "account_name": "string", "account_username": "string", "account_avatar_url": "https://example.com", "status": "pending", "content": "string", "media_ids": [ "string" ], "platform_options": {}, "first_comment": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "external_id": "string", "url": "https://example.com", "error": "string", "error_code": "string", "error_category": "string", "warnings": [ "string" ], "result": {}, "credits_charged": 1, "attempts": 1, "unpublished_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get publishing settings `GET /publishing/settings` Approval workflow settings and the plan publishing limits. Access: `read` · MCP tool: `get-publishing-settings` ```bash curl "https://api.socialit.com/v1/publishing/settings" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "publishing_settings", "require_approval": true, "approver_ids": [ "string" ], "default_timezone": "string", "posts_per_account_per_day": 1, "posts_per_month": 1, "posts_this_month": 1 } ``` ## Update publishing settings `PATCH /publishing/settings` Access: `admin` · MCP tool: `update-publishing-settings` ### Body - `require_approval` (boolean) - `approver_ids` (array of string; ≤ 100 items) - `default_timezone` (string | null; ≤ 64 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/publishing/settings" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "require_approval": true, "approver_ids": [ "usr_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ], "default_timezone": "string" }' ``` Response 200: ```json { "object": "publishing_settings", "require_approval": true, "approver_ids": [ "string" ], "default_timezone": "string", "posts_per_account_per_day": 1, "posts_per_month": 1, "posts_this_month": 1 } ``` --- Source: https://socialit.com/docs/api-reference/posts/ # Queues API > Recurring posting schedules. Posts created with queue: true take the next free slot. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List queues `GET /queues` Access: `read` · MCP tool: `list-queues` · Zernio: `GET /v1/queue/slots` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string) - `standalone` (boolean) - `active` (boolean) ```bash curl "https://api.socialit.com/v1/queues" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "queue", "id": "string", "profile_id": "string", "name": "string", "timezone": "Europe/Prague", "active": true, "default": true, "slots": [ { "day_of_week": 1, "time": "string" } ], "next_slots": [ "string" ], "posts_count": 1, "reshuffled_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a queue `POST /queues` The first queue of a profile (or of the standalone bucket) becomes its default. Access: `write` · MCP tool: `create-queue` · Zernio: `POST /v1/queue/slots` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string | null; ≤ 80 characters) - `name` (string; required; 1–100 characters) - `timezone` (string; ≤ 64 characters) - `slots` (array of object; ≤ 200 items) - `slots[].day_of_week` (integer; required; 0–6) - `slots[].time` (string; required; pattern ^([01]\d|2[0-3]):[0-5]\d$) - `active` (boolean) - `default` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/queues" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "name": "string", "timezone": "Europe/Prague", "slots": [ { "day_of_week": 0, "time": "string" } ], "active": true }' ``` Response 201: ```json { "object": "queue", "id": "string", "profile_id": "string", "name": "string", "timezone": "Europe/Prague", "active": true, "default": true, "slots": [ { "day_of_week": 1, "time": "string" } ], "next_slots": [ "string" ], "posts_count": 1, "reshuffled_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Preview upcoming free slots `GET /queues/preview` Access: `read` · MCP tool: `preview-queue` · Zernio: `GET /v1/queue/preview` ### Query parameters - `queue_id` (string) - `profile_id` (string) - `count` (integer; 1–100) ```bash curl "https://api.socialit.com/v1/queues/preview" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "queue_preview", "queue_id": "string", "profile_id": "string", "timezone": "Europe/Prague", "slots": [ "string" ] } ``` ## Get the next free slot `GET /queues/next-slot` Informational: to book a slot create the post with queue: true (slot assignment is atomic there). Access: `read` · MCP tool: `get-next-queue-slot` · Zernio: `GET /v1/queue/next-slot` ### Query parameters - `queue_id` (string) - `profile_id` (string) ```bash curl "https://api.socialit.com/v1/queues/next-slot" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "queue_slot", "queue_id": "string", "profile_id": "string", "timezone": "Europe/Prague", "slot": "2026-10-13T09:00:00.000Z" } ``` ## Get a queue `GET /queues/{id}` Access: `read` · MCP tool: `get-queue` ### Path parameters - `id` (string; required; 1–80 characters): queue id (que_…) ```bash curl "https://api.socialit.com/v1/queues/que_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "queue", "id": "string", "profile_id": "string", "name": "string", "timezone": "Europe/Prague", "active": true, "default": true, "slots": [ { "day_of_week": 1, "time": "string" } ], "next_slots": [ "string" ], "posts_count": 1, "reshuffled_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a queue `PATCH /queues/{id}` Rename, change timezone or slots, (de)activate, set as default; reshuffle_existing moves already-queued posts onto the new slots. Access: `write` · MCP tool: `update-queue` · Zernio: `PUT /v1/queue/slots` ### Path parameters - `id` (string; required; 1–80 characters): queue id (que_…) ### Body - `name` (string; 1–100 characters) - `timezone` (string; ≤ 64 characters) - `slots` (array of object; ≤ 200 items) - `slots[].day_of_week` (integer; required; 0–6) - `slots[].time` (string; required; pattern ^([01]\d|2[0-3]):[0-5]\d$) - `active` (boolean) - `default` (boolean) - `set_as_default` (boolean): Zernio alias of default - `reshuffle_existing` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/queues/que_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "timezone": "Europe/Prague", "slots": [ { "day_of_week": 0, "time": "string" } ], "active": true, "default": true }' ``` Response 200: ```json { "object": "queue", "id": "string", "profile_id": "string", "name": "string", "timezone": "Europe/Prague", "active": true, "default": true, "slots": [ { "day_of_week": 1, "time": "string" } ], "next_slots": [ "string" ], "posts_count": 1, "reshuffled_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a queue `DELETE /queues/{id}` Access: `write` · MCP tool: `delete-queue` · Zernio: `DELETE /v1/queue/slots` ### Path parameters - `id` (string; required; 1–80 characters): queue id (que_…) ```bash curl -X DELETE "https://api.socialit.com/v1/queues/que_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "queue", "id": "string", "deleted": true } ``` --- Source: https://socialit.com/docs/api-reference/queues/ # Media API > Upload images, videos and documents for posts (and inbox attachments). Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## Get an upload URL `POST /media/presign` Returns a URL to PUT the file to (S3/R2 bucket when configured, else the API). Reference the returned media id (or public_url) in posts. Access: `write` · MCP tool: `presign-media-upload` · Zernio: `POST /v1/media/presign` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `filename` (string; required; 1–255 characters) - `content_type` (string; required; 3–100 characters) - `size` (integer) - `folder` (string; ≤ 200 characters) - `tags` (array of string; ≤ 50 items) - `alt_text` (string; ≤ 2000 characters) ```bash curl -X POST "https://api.socialit.com/v1/media/presign" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "filename": "string", "content_type": "string", "size": 0, "folder": "string", "tags": [ "string" ] }' ``` Response 201: ```json { "object": "media_upload", "media": { "object": "media", "id": "string", "status": "pending", "type": "string", "name": "string", "file_name": "string", "mime_type": "string", "size": 1, "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "caption": "string", "tags": [ "string" ], "folder": "string", "storage": "local", "source_url": "https://example.com", "used_in_posts": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" }, "upload_url": "https://example.com", "method": "PUT", "headers": { "key": "string" }, "public_url": "https://example.com", "expires_in": 1 } ``` ## Upload a file `POST /media/upload-direct` multipart/form-data with a file field (+ optional folder, alt_text, tags). Image ≤ 20 MB, GIF ≤ 15 MB, video ≤ 500 MB, document/audio ≤ 100 MB. Access: `write` · Zernio: `POST /v1/media/upload-direct` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/media/upload-direct" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 201: ```json { "object": "media", "id": "string", "status": "pending", "type": "string", "name": "string", "file_name": "string", "mime_type": "string", "size": 1, "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "caption": "string", "tags": [ "string" ], "folder": "string", "storage": "local", "source_url": "https://example.com", "used_in_posts": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List the media library `GET /media` Access: `read` · MCP tool: `list-media-library` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, size, name) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `type` (string; one of image, video, gif, document, audio) - `status` (string; one of pending, processing, ready, failed) - `folder` (string) - `tag` (string) - `search` (string; ≤ 200 characters) ```bash curl "https://api.socialit.com/v1/media" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "media", "id": "string", "status": "pending", "type": "string", "name": "string", "file_name": "string", "mime_type": "string", "size": 1, "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "caption": "string", "tags": [ "string" ], "folder": "string", "storage": "local", "source_url": "https://example.com", "used_in_posts": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Register media from a public URL `POST /media` Access: `write` · MCP tool: `create-media-from-url` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `url` (string; required; 8–2048 characters) - `name` (string; ≤ 255 characters) - `type` (string; one of image, video, gif, document, audio) - `alt_text` (string; ≤ 2000 characters) - `caption` (string; ≤ 5000 characters) - `tags` (array of string; ≤ 50 items) - `folder` (string; ≤ 200 characters) ```bash curl -X POST "https://api.socialit.com/v1/media" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "name": "string", "type": "image", "alt_text": "string", "caption": "string" }' ``` Response 201: ```json { "object": "media", "id": "string", "status": "pending", "type": "string", "name": "string", "file_name": "string", "mime_type": "string", "size": 1, "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "caption": "string", "tags": [ "string" ], "folder": "string", "storage": "local", "source_url": "https://example.com", "used_in_posts": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Media storage usage `GET /media/usage` Access: `read` · MCP tool: `get-media-usage` ```bash curl "https://api.socialit.com/v1/media/usage" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "media_usage", "used_bytes": 1, "limit_bytes": 1, "files": 1, "by_type": { "key": 1 } } ``` ## List media folders `GET /media/folders` Access: `read` · MCP tool: `list-media-folders` ```bash curl "https://api.socialit.com/v1/media/folders" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "media_folder", "name": "string", "count": 1 } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get media `GET /media/{id}` Access: `read` · MCP tool: `get-media-item` ### Path parameters - `id` (string; required; 1–80 characters): media id (med_…) ```bash curl "https://api.socialit.com/v1/media/med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "media", "id": "string", "status": "pending", "type": "string", "name": "string", "file_name": "string", "mime_type": "string", "size": 1, "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "caption": "string", "tags": [ "string" ], "folder": "string", "storage": "local", "source_url": "https://example.com", "used_in_posts": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update media `PATCH /media/{id}` Name, alt text, caption, tags and folder. Access: `write` · MCP tool: `update-media-item` ### Path parameters - `id` (string; required; 1–80 characters): media id (med_…) ### Body - `name` (string; 1–255 characters) - `alt_text` (string | null; ≤ 2000 characters) - `caption` (string | null; ≤ 5000 characters) - `tags` (array of string; ≤ 50 items) - `folder` (string | null; ≤ 200 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/media/med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "alt_text": "string", "caption": "string", "tags": [ "string" ], "folder": "string" }' ``` Response 200: ```json { "object": "media", "id": "string", "status": "pending", "type": "string", "name": "string", "file_name": "string", "mime_type": "string", "size": 1, "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "caption": "string", "tags": [ "string" ], "folder": "string", "storage": "local", "source_url": "https://example.com", "used_in_posts": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete media `DELETE /media/{id}` Access: `write` · MCP tool: `delete-media-item` ### Path parameters - `id` (string; required; 1–80 characters): media id (med_…) ```bash curl -X DELETE "https://api.socialit.com/v1/media/med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "media", "id": "string", "deleted": true } ``` ## Finalize a presigned upload `POST /media/{id}/complete` Access: `write` · MCP tool: `complete-media-upload` ### Path parameters - `id` (string; required; 1–80 characters): media id (med_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/media/med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/complete" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 200: ```json { "object": "media", "id": "string", "status": "pending", "type": "string", "name": "string", "file_name": "string", "mime_type": "string", "size": 1, "url": "https://example.com", "thumbnail_url": "https://example.com", "preview_url": "https://example.com", "width": 1, "height": 1, "duration": 1, "alt_text": "string", "caption": "string", "tags": [ "string" ], "folder": "string", "storage": "local", "source_url": "https://example.com", "used_in_posts": 1, "created_by": { "type": "string", "id": "string", "name": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` --- Source: https://socialit.com/docs/api-reference/media/ # Templates API > Reusable post content with media and network options. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List templates `GET /templates` Access: `read` · MCP tool: `list-templates` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name, updated_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `search` (string; ≤ 200 characters) - `tag` (string) ```bash curl "https://api.socialit.com/v1/templates" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "template", "id": "string", "name": "string", "alias": "string", "content": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "position": 1 } ], "platform_options": {}, "first_comment": "string", "tags": [ "string" ], "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a template `POST /templates` Access: `write` · MCP tool: `create-template` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–200 characters) - `alias` (string | null; ≤ 100 characters) - `content` (string; required; ≤ 63206 characters) - `media_ids` (array of string; ≤ 35 items) - `platform_options` (object) - `first_comment` (string | null; ≤ 10000 characters) - `tags` (array of string; ≤ 50 items) ```bash curl -X POST "https://api.socialit.com/v1/templates" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "alias": "string", "content": "string", "media_ids": [ "med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ], "platform_options": {} }' ``` Response 201: ```json { "object": "template", "id": "string", "name": "string", "alias": "string", "content": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "position": 1 } ], "platform_options": {}, "first_comment": "string", "tags": [ "string" ], "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get a template `GET /templates/{id}` Access: `read` · MCP tool: `get-template` ### Path parameters - `id` (string; required; 1–80 characters): template id (tem_…) ```bash curl "https://api.socialit.com/v1/templates/tem_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "template", "id": "string", "name": "string", "alias": "string", "content": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "position": 1 } ], "platform_options": {}, "first_comment": "string", "tags": [ "string" ], "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a template `PATCH /templates/{id}` Access: `write` · MCP tool: `update-template` ### Path parameters - `id` (string; required; 1–80 characters): template id (tem_…) ### Body - `name` (string; 1–200 characters) - `alias` (string | null; ≤ 100 characters) - `content` (string; ≤ 63206 characters) - `media_ids` (array of string; ≤ 35 items) - `platform_options` (object) - `first_comment` (string | null; ≤ 10000 characters) - `tags` (array of string; ≤ 50 items) ```bash curl -X PATCH "https://api.socialit.com/v1/templates/tem_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "alias": "string", "content": "string", "media_ids": [ "med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ], "platform_options": {} }' ``` Response 200: ```json { "object": "template", "id": "string", "name": "string", "alias": "string", "content": "string", "media": [ { "media_id": "string", "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com", "position": 1 } ], "platform_options": {}, "first_comment": "string", "tags": [ "string" ], "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a template `DELETE /templates/{id}` Access: `write` · MCP tool: `delete-template` ### Path parameters - `id` (string; required; 1–80 characters): template id (tem_…) ```bash curl -X DELETE "https://api.socialit.com/v1/templates/tem_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "template", "id": "string", "deleted": true } ``` --- Source: https://socialit.com/docs/api-reference/templates/ # Tools API > Validate posts and media before publishing; feedback and changelog. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## Character counts per network `POST /tools/validate/post-length` Weighted counts (X: URLs = 23, emoji/CJK = 2; x_premium = 25,000). Access: `read` · MCP tool: `validate-post-length` · Zernio: `POST /v1/tools/validate/post-length` ### Body - `text` (string; required; ≤ 100000 characters) - `platforms` (array of string) ```bash curl -X POST "https://api.socialit.com/v1/tools/validate/post-length" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "string", "platforms": [ "string" ] }' ``` Response 200: ```json { "object": "post_length", "text_length": 1, "platforms": { "key": { "length": 1, "limit": 1, "remaining": 1, "valid": true } } } ``` ## Validate a post for its target networks `POST /tools/validate/post` Same body as POST /posts; nothing is created. Runs shared limits, each network validator and platform_options schemas. Access: `read` · MCP tool: `validate-post` · Zernio: `POST /v1/tools/validate/post` ### Body - `content` (string; ≤ 63206 characters) - `title` (string | null; ≤ 300 characters) - `account_ids` (array of string; ≤ 200 items) - `profile_id` (string | null; ≤ 80 characters) - `group_id` (string; ≤ 80 characters) - `platforms` (array of string; ≤ 30 items) - `targets` (array of object; ≤ 200 items) - `targets[].account_id` (string; required; 1–80 characters): socialAccount id (sa_…) - `targets[].content` (string; ≤ 63206 characters) - `targets[].media_ids` (array of string; ≤ 35 items) - `targets[].media_urls` (array of any; ≤ 35 items): Public HTTPS URLs or { url, alt_text?, type? } - `targets[].media` (array of object; ≤ 35 items) - `targets[].media[].media_id` (string; 1–80 characters): media id (med_…) - `targets[].media[].url` (string; ≤ 2048 characters) - `targets[].media[].alt_text` (string; ≤ 2000 characters) - `targets[].media[].type` (string; one of image, video, gif, document) - `targets[].platform_options` (object) - `targets[].first_comment` (string; ≤ 10000 characters) - `targets[].scheduled_at` (string; ≤ 40 characters) - `media_ids` (array of string; ≤ 35 items) - `media_urls` (array of any; ≤ 35 items): Public HTTPS URLs or { url, alt_text?, type? } - `media` (array of object; ≤ 35 items) - `media[].media_id` (string; 1–80 characters): media id (med_…) - `media[].url` (string; ≤ 2048 characters) - `media[].alt_text` (string; ≤ 2000 characters) - `media[].type` (string; one of image, video, gif, document) - `platform_options` (object) - `first_comment` (string | null; ≤ 10000 characters) - `thread_items` (array of object; ≤ 25 items) - `thread_items[].content` (string; required; ≤ 63206 characters) - `thread_items[].media_ids` (array of string; ≤ 10 items) - `quote_post_id` (string | null; ≤ 80 characters) - `quote_url` (string | null; ≤ 2048 characters) - `reply_to_url` (string | null; ≤ 2048 characters) - `scheduled_at` (string | null; ≤ 40 characters): ISO 8601; without offset = wall clock in timezone - `timezone` (string | null; ≤ 64 characters) - `publish_now` (boolean) - `queue` (boolean) - `queue_id` (string | null; ≤ 80 characters) - `draft` (boolean) - `tags` (array of string; ≤ 50 items) - `metadata` (object) - `strict` (boolean) - `recycle` (object | null) - `recycle.enabled` (boolean; required) - `recycle.interval` (integer; 1–365) - `recycle.interval_unit` (string; one of day, week, month) - `recycle.start_at` (string (date-time)) - `recycle.max_count` (integer | null; 1–1000) - `recycle.expires_at` (string (date-time) | null) - `recycle.content_variations` (array of string; ≤ 20 items) - `note` (string; ≤ 5000 characters) ```bash curl -X POST "https://api.socialit.com/v1/tools/validate/post" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "string", "title": "string", "account_ids": [ "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ], "profile_id": "string", "group_id": "string" }' ``` Response 200: ```json { "object": "post_validation", "valid": true, "errors": [ { "account_id": "string", "platform": "string", "code": "string", "message": "string", "param": "string" } ], "warnings": [ { "account_id": "string", "platform": "string", "code": "string", "message": "string", "param": "string" } ], "targets": [ { "account_id": "string", "platform": "string", "valid": true, "length": 1, "limit": 1, "errors": [ "string" ], "warnings": [ "string" ] } ] } ``` ## Validate a media URL or library item `POST /tools/validate/media` Access: `read` · MCP tool: `validate-media-url` · Zernio: `POST /v1/tools/validate/media` ### Body - `url` (string; ≤ 2048 characters) - `media_id` (string; 1–80 characters): media id (med_…) - `platforms` (array of string) ```bash curl -X POST "https://api.socialit.com/v1/tools/validate/media" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "media_id": "med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platforms": [ "string" ] }' ``` Response 200: ```json { "object": "media_validation", "valid": true, "url": "https://example.com", "content_type": "string", "size": 1, "size_formatted": "string", "type": "string", "platforms": { "key": { "valid": true, "max_bytes": 1, "errors": [ "string" ] } }, "errors": [ "string" ] } ``` ## Check a subreddit `GET /tools/validate/subreddit` Existence, posting restrictions, rules and post requirements, through a connected Reddit account. Access: `read` · MCP tool: `validate-subreddit` · Zernio: `GET /v1/tools/validate/subreddit` ### Query parameters - `name` (string; required; 1–100 characters) - `account_id` (string) ```bash curl "https://api.socialit.com/v1/tools/validate/subreddit?name=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "subreddit_validation", "name": "string", "exists": true, "valid": true, "subreddit": {} } ``` ## TikTok video metadata `GET /tools/tiktok/download` Metadata and embed only: TikTok's official APIs don't allow downloading videos (download_url is always null). Access: `read` · MCP tool: `download-tik-tok-video` · Zernio: `GET /v1/tools/tiktok/download` ### Query parameters - `url` (string; required; 10–2048 characters) - `action` (string; one of download, metadata) - `format_id` (string) ```bash curl "https://api.socialit.com/v1/tools/tiktok/download?url=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "tiktok_video", "url": "https://example.com", "video_id": "string", "author": "string", "title": "string", "thumbnail_url": "https://example.com", "embed_html": "string", "download_url": "https://example.com", "unavailable_reason": "string", "formats": [ {} ] } ``` ## Send feedback to the Socialit team `POST /feedback` Bugs, missing features and docs issues; built for AI agents too. Access: `read` · MCP tool: `submit-feedback` · Zernio: `POST /v1/feedback` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `type` (string; required; one of bug, missing_feature, docs, other) - `summary` (string; required; 3–500 characters) - `details` (string; ≤ 10000 characters) - `endpoint` (string; ≤ 300 characters) - `request_id` (string; ≤ 100 characters) - `expected` (string; ≤ 5000 characters) - `actual` (string; ≤ 5000 characters) - `agent` (string; ≤ 100 characters) ```bash curl -X POST "https://api.socialit.com/v1/feedback" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "type": "bug", "summary": "string", "details": "string", "endpoint": "string", "request_id": "string" }' ``` Response 201: ```json { "object": "feedback", "id": "string", "type": "string", "summary": "string", "details": "string", "endpoint": "string", "request_id": "string", "expected": "string", "actual": "string", "agent": "string", "created_at": "2026-10-13T09:00:00.000Z" } ``` ## API changelog `GET /changelog` Access: `read` · MCP tool: `list-changelog` · Zernio: `GET /v1/changelog` ### Query parameters - `type` (string; one of new_feature, improvement, breaking_change, deprecation, fix) - `impact` (string; one of low, medium, high) - `platform` (string) - `before` (string; ≤ 30 characters) - `limit` (integer; 1–100) ```bash curl "https://api.socialit.com/v1/changelog" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "changelog_entry", "id": "string", "date": "string", "type": "string", "impact": "string", "title": "string", "description": "string", "platforms": [ "string" ], "operations": [ "string" ], "url": "https://example.com" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` --- Source: https://socialit.com/docs/api-reference/tools/ # Inbox API > Unified inbox: direct messages, comments, reviews and mentions across networks, plus messaging settings, X engagement and Reddit discovery. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List conversations `GET /inbox/conversations` Direct-message conversations of every connected account the caller can see, newest activity first. Filter by profile, account, platform, status, folder (message requests), assignee, label or unread. Access: `read` · MCP tool: `list-conversations` · Zernio: `GET /v1/inbox/conversations` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of last_message_at, created_at, unread_count) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string): Only items of this profile (pro_…) - `account_id` (string): Only items of this account (sa_…) - `platform` (string; one of facebook, instagram, x, linkedin, threads, bluesky, pinterest, tiktok, youtube, google_business, reddit, snapchat, …) - `status` (string; one of open, active, archived, snoozed) - `folder` (string; one of inbox, requests) - `assignee_id` (string): usr_… or "none" for unassigned - `label` (string) - `unread` (boolean) - `q` (string; ≤ 200 characters): Participant name / username contains ```bash curl "https://api.socialit.com/v1/inbox/conversations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "conversation", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "participant": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "is_group": true, "folder": "inbox", "status": "open", "snoozed_until": "2026-10-13T09:00:00.000Z", "unread_count": 1, "assignee_id": "string", "labels": [ "string" ], "thread_owner": "string", "contact_id": "string", "last_message_preview": "string", "last_message_direction": "inbound", "last_message_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "url": "https://example.com", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Start a conversation `POST /inbox/conversations` Open a direct-message thread with a user (X, Bluesky, Reddit, Discord, Mastodon). If a thread with that participant exists, the message is added to it. Access: `write` · MCP tool: `create-conversation` · Zernio: `POST /v1/inbox/conversations` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `participant_id` (string; 1–300 characters) - `participant_username` (string; 1–300 characters) - `text` (string; 1–20000 characters) - `media_ids` (array of string; ≤ 10 items) - `attachment_url` (string (uri)) - `attachment_type` (string; one of image, video, audio, file) - `skip_dm_check` (boolean) - `template` (object) - `template.name` (string; required; ≥ 1 characters) - `template.language` (string) - `template.params` (array of string) - `template.button_params` (array of object) - `template.cards` (array of object) - `template.header_media` (object) - `template.header_location` (object) - `category` (string; one of utility, marketing, authentication) - `link_preview` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/inbox/conversations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "participant_id": "string", "participant_username": "string", "text": "string", "media_ids": [ "med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ] }' ``` Response 201: ```json { "object": "conversation", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "participant": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "is_group": true, "folder": "inbox", "status": "open", "snoozed_until": "2026-10-13T09:00:00.000Z", "unread_count": 1, "assignee_id": "string", "labels": [ "string" ], "thread_owner": "string", "contact_id": "string", "last_message_preview": "string", "last_message_direction": "inbound", "last_message_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "url": "https://example.com", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "sent_message": { "object": "message", "id": "string", "conversation_id": "string", "account_id": "string", "platform": "string", "external_id": "string", "direction": "inbound", "text": "string", "sender": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "attachments": [ { "index": 1, "type": "string", "url": "https://example.com", "mime_type": "string", "filename": "string", "size": 1 } ], "status": "string", "error": { "code": "string", "message": "string" }, "reactions": [ { "emoji": "string", "from_me": true, "sender_id": "string", "reacted_at": "2026-10-13T09:00:00.000Z" } ], "reply_to_id": "string", "reply_to_external_id": "string", "is_edited": true, "edited_at": "2026-10-13T09:00:00.000Z", "edit_count": 1, "edit_history": [ { "text": "string", "edited_at": "2026-10-13T09:00:00.000Z" } ], "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "sent_via": "string", "sent_by_user_id": "string", "sent_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z", "read_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } } ``` ## Search conversations `GET /inbox/conversations/search` Search message text and participant identity (name, username, id). Each result carries up to 3 matching messages, most recent match first. Access: `read` · MCP tool: `search-conversations` · Zernio: `GET /v1/inbox/conversations/search` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string): Only items of this profile (pro_…) - `account_id` (string): Only items of this account (sa_…) - `platform` (string; one of facebook, instagram, x, linkedin, threads, bluesky, pinterest, tiktok, youtube, google_business, reddit, snapchat, …) - `q` (string; 1–200 characters): Text to search in messages and participant identity - `query` (string; 1–200 characters): Alias of q (Zernio) - `direction` (string; one of inbound, outbound, incoming, outgoing) ```bash curl "https://api.socialit.com/v1/inbox/conversations/search" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "conversation_search_result", "conversation": { "object": "conversation", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" } }, "match_count": 1, "matches": [ { "id": "string", "text": "string", "direction": "inbound", "sent_at": "2026-10-13T09:00:00.000Z" } ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a conversation `GET /inbox/conversations/{conversationId}` Access: `read` · MCP tool: `get-conversation` · Zernio: `GET /v1/inbox/conversations/{conversationId}` ### Path parameters - `conversationId` (string; required; 1–80 characters): Conversation id (conv_…) ```bash curl "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "conversation", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "participant": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "is_group": true, "folder": "inbox", "status": "open", "snoozed_until": "2026-10-13T09:00:00.000Z", "unread_count": 1, "assignee_id": "string", "labels": [ "string" ], "thread_owner": "string", "contact_id": "string", "last_message_preview": "string", "last_message_direction": "inbound", "last_message_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "url": "https://example.com", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a conversation `PATCH /inbox/conversations/{conversationId}` Archive, reopen or snooze a conversation, assign it to a workspace member, set labels or link a contact. Access: `write` · MCP tool: `update-conversation` · Zernio: `PUT /v1/inbox/conversations/{conversationId}` ### Path parameters - `conversationId` (string; required; 1–80 characters): Conversation id (conv_…) ### Body - `status` (string; one of open, active, archived, snoozed) - `snoozed_until` (string (date-time) | null) - `assignee_id` (string | null) - `labels` (array of string; ≤ 20 items) - `contact_id` (string | null) - `account_id` (string): Ignored (Zernio compatibility) ```bash curl -X PATCH "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "open", "snoozed_until": "2026-10-13T09:00:00.000Z", "assignee_id": "string", "labels": [ "string" ], "contact_id": "string" }' ``` Response 200: ```json { "object": "conversation", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "participant": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "is_group": true, "folder": "inbox", "status": "open", "snoozed_until": "2026-10-13T09:00:00.000Z", "unread_count": 1, "assignee_id": "string", "labels": [ "string" ], "thread_owner": "string", "contact_id": "string", "last_message_preview": "string", "last_message_direction": "inbound", "last_message_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "url": "https://example.com", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Accept a message request `POST /inbox/conversations/{conversationId}/accept` Accept a Facebook / Instagram (or Bluesky) message request by replying to it; the thread moves to the inbox folder. Access: `write` · MCP tool: `accept-conversation` · Zernio: `POST /v1/inbox/conversations/{conversationId}/accept` ### Path parameters - `conversationId` (string; required; 1–80 characters): Conversation id (conv_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `text` (string; required; 1–20000 characters) - `account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/accept" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "text": "string", "account_id": "string" }' ``` Response 200: ```json { "object": "message", "id": "string", "conversation_id": "string", "account_id": "string", "platform": "string", "external_id": "string", "direction": "inbound", "text": "string", "sender": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "attachments": [ { "index": 1, "type": "string", "url": "https://example.com", "mime_type": "string", "filename": "string", "size": 1, "preview_url": "https://example.com", "media_id": "string", "refresh_url": "https://example.com" } ], "status": "string", "error": { "code": "string", "message": "string" }, "reactions": [ { "emoji": "string", "from_me": true, "sender_id": "string", "reacted_at": "2026-10-13T09:00:00.000Z" } ], "reply_to_id": "string", "reply_to_external_id": "string", "is_edited": true, "edited_at": "2026-10-13T09:00:00.000Z", "edit_count": 1, "edit_history": [ { "text": "string", "edited_at": "2026-10-13T09:00:00.000Z" } ], "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "sent_via": "string", "sent_by_user_id": "string", "sent_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z", "read_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Mark a conversation as read `POST /inbox/conversations/{conversationId}/read` Marks every unread inbound message as read and sends read receipts where the network supports them (Messenger, Instagram, Bluesky, TikTok, Reddit, Mastodon). Access: `write` · MCP tool: `mark-conversation-read` · Zernio: `POST /v1/inbox/conversations/{conversationId}/read` ### Path parameters - `conversationId` (string; required; 1–80 characters): Conversation id (conv_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/read" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "string" }' ``` Response 200: ```json { "object": "conversation", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "participant": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "is_group": true, "folder": "inbox", "status": "open", "snoozed_until": "2026-10-13T09:00:00.000Z", "unread_count": 1, "assignee_id": "string", "labels": [ "string" ], "thread_owner": "string", "contact_id": "string", "last_message_preview": "string", "last_message_direction": "inbound", "last_message_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "url": "https://example.com", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Mark a conversation as unread `POST /inbox/conversations/{conversationId}/unread` Flags the conversation unread in Socialit (no network call). Access: `write` · MCP tool: `mark-conversation-unread` ### Path parameters - `conversationId` (string; required; 1–80 characters): Conversation id (conv_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/unread" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 200: ```json { "object": "conversation", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "participant": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "is_group": true, "folder": "inbox", "status": "open", "snoozed_until": "2026-10-13T09:00:00.000Z", "unread_count": 1, "assignee_id": "string", "labels": [ "string" ], "thread_owner": "string", "contact_id": "string", "last_message_preview": "string", "last_message_direction": "inbound", "last_message_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "url": "https://example.com", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Send a typing indicator `POST /inbox/conversations/{conversationId}/typing` Access: `write` · MCP tool: `send-typing-indicator` · Zernio: `POST /v1/inbox/conversations/{conversationId}/typing` ### Path parameters - `conversationId` (string; required; 1–80 characters): Conversation id (conv_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/typing" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "string" }' ``` Response 200: ```json { "object": "typing_indicator", "conversation_id": "string", "sent": true } ``` ## Change who answers a conversation `POST /inbox/conversations/{conversationId}/thread-control` Meta's handover protocol: take, pass, release or request thread control. Access: `write` · MCP tool: `change-thread-control` · Zernio: `POST /v1/inbox/conversations/{conversationId}/thread-control` ### Path parameters - `conversationId` (string; required; 1–80 characters): Conversation id (conv_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `action` (string; required; one of release, take, pass, request) - `target` (string; one of ai_agent) - `target_app_id` (string; ≤ 100 characters) - `metadata` (string; ≤ 1000 characters) - `account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/thread-control" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "action": "release", "target": "ai_agent", "target_app_id": "string", "metadata": "string", "account_id": "string" }' ``` Response 200: ```json { "object": "thread_control", "conversation_id": "string", "owner": "string", "owner_app_id": "string" } ``` ## List messages `GET /inbox/conversations/{conversationId}/messages` Messages of a conversation, oldest first by default (order=desc for the latest). refresh=true pulls the newest messages from the network first. Access: `read` · MCP tool: `list-messages` · Zernio: `GET /v1/inbox/conversations/{conversationId}/messages` ### Path parameters - `conversationId` (string; required; 1–80 characters): Conversation id (conv_…) ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of sent_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `direction` (string; one of inbound, outbound) - `refresh` (boolean): Pull the latest messages from the network first ```bash curl "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messages" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "message", "id": "string", "conversation_id": "string", "account_id": "string", "platform": "string", "external_id": "string", "direction": "inbound", "text": "string", "sender": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "attachments": [ { "index": 1, "type": "string", "url": "https://example.com", "mime_type": "string", "filename": "string", "size": 1 } ], "status": "string", "error": { "code": "string", "message": "string" }, "reactions": [ { "emoji": "string", "from_me": true, "sender_id": "string", "reacted_at": "2026-10-13T09:00:00.000Z" } ], "reply_to_id": "string", "reply_to_external_id": "string", "is_edited": true, "edited_at": "2026-10-13T09:00:00.000Z", "edit_count": 1, "edit_history": [ { "text": "string", "edited_at": "2026-10-13T09:00:00.000Z" } ], "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "sent_via": "string", "sent_by_user_id": "string", "sent_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z", "read_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Send a message `POST /inbox/conversations/{conversationId}/messages` Send text, media (media_ids from the media library or a public attachment_url), quick replies, buttons, templates, interactive messages, locations or contacts. Support varies by network. Access: `write` · MCP tool: `send-message` · Zernio: `POST /v1/inbox/conversations/{conversationId}/messages` ### Path parameters - `conversationId` (string; required; 1–80 characters): Conversation id (conv_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `text` (string; 1–20000 characters) - `media_ids` (array of string; ≤ 10 items) - `attachment_url` (string (uri)) - `attachment_type` (string; one of image, video, audio, file) - `attachment_name` (string; ≤ 255 characters) - `quick_replies` (array of object; ≤ 13 items) - `quick_replies[].title` (string; required; 1–20 characters) - `quick_replies[].payload` (string; required; ≤ 1000 characters) - `quick_replies[].image_url` (string) - `buttons` (array of object; ≤ 3 items) - `buttons[].type` (string; required; one of url, postback, phone) - `buttons[].title` (string; required; 1–20 characters) - `buttons[].url` (string) - `buttons[].payload` (string) - `buttons[].phone` (string) - `template` (object) - `messaging_type` (string; one of RESPONSE, UPDATE, MESSAGE_TAG) - `message_tag` (string; one of CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE, HUMAN_AGENT) - `reply_to` (string; ≤ 300 characters) - `subject` (string; ≤ 300 characters) - `account_id` (string): Ignored (Zernio compatibility) ```bash curl -X POST "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messages" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "text": "string", "media_ids": [ "med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ], "attachment_url": "https://example.com", "attachment_type": "image", "attachment_name": "string" }' ``` Response 201: ```json { "object": "message", "id": "string", "conversation_id": "string", "account_id": "string", "platform": "string", "external_id": "string", "direction": "inbound", "text": "string", "sender": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "attachments": [ { "index": 1, "type": "string", "url": "https://example.com", "mime_type": "string", "filename": "string", "size": 1, "preview_url": "https://example.com", "media_id": "string", "refresh_url": "https://example.com" } ], "status": "string", "error": { "code": "string", "message": "string" }, "reactions": [ { "emoji": "string", "from_me": true, "sender_id": "string", "reacted_at": "2026-10-13T09:00:00.000Z" } ], "reply_to_id": "string", "reply_to_external_id": "string", "is_edited": true, "edited_at": "2026-10-13T09:00:00.000Z", "edit_count": 1, "edit_history": [ { "text": "string", "edited_at": "2026-10-13T09:00:00.000Z" } ], "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "sent_via": "string", "sent_by_user_id": "string", "sent_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z", "read_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a message `DELETE /inbox/conversations/{conversationId}/messages/{messageId}` Delete / unsend a message (X, Bluesky for self, Reddit). Access: `write` · MCP tool: `delete-message` · Zernio: `DELETE /v1/inbox/conversations/{conversationId}/messages/{messageId}` ### Path parameters - `conversationId` (string; required; 1–80 characters): conversation id (conv_…) - `messageId` (string; required; 1–500 characters): Message id (msg_…) or the network message id ```bash curl -X DELETE "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messages/MESSAGE_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "message", "id": "string", "deleted": true } ``` ## React to a message `POST /inbox/conversations/{conversationId}/messages/{messageId}/reactions` Access: `write` · MCP tool: `add-message-reaction` · Zernio: `POST /v1/inbox/conversations/{conversationId}/messages/{messageId}/reactions` ### Path parameters - `conversationId` (string; required; 1–80 characters): conversation id (conv_…) - `messageId` (string; required; 1–500 characters): Message id (msg_…) or the network message id ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `emoji` (string; required; 1–64 characters) - `account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messages/MESSAGE_ID/reactions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "emoji": "string", "account_id": "string" }' ``` Response 200: ```json { "object": "message", "id": "string", "conversation_id": "string", "account_id": "string", "platform": "string", "external_id": "string", "direction": "inbound", "text": "string", "sender": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "attachments": [ { "index": 1, "type": "string", "url": "https://example.com", "mime_type": "string", "filename": "string", "size": 1, "preview_url": "https://example.com", "media_id": "string", "refresh_url": "https://example.com" } ], "status": "string", "error": { "code": "string", "message": "string" }, "reactions": [ { "emoji": "string", "from_me": true, "sender_id": "string", "reacted_at": "2026-10-13T09:00:00.000Z" } ], "reply_to_id": "string", "reply_to_external_id": "string", "is_edited": true, "edited_at": "2026-10-13T09:00:00.000Z", "edit_count": 1, "edit_history": [ { "text": "string", "edited_at": "2026-10-13T09:00:00.000Z" } ], "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "sent_via": "string", "sent_by_user_id": "string", "sent_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z", "read_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Remove a reaction `DELETE /inbox/conversations/{conversationId}/messages/{messageId}/reactions` Access: `write` · MCP tool: `remove-message-reaction` · Zernio: `DELETE /v1/inbox/conversations/{conversationId}/messages/{messageId}/reactions` ### Path parameters - `conversationId` (string; required; 1–80 characters): conversation id (conv_…) - `messageId` (string; required; 1–500 characters): Message id (msg_…) or the network message id ### Query parameters - `emoji` (string; ≤ 64 characters) - `account_id` (string) ```bash curl -X DELETE "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messages/MESSAGE_ID/reactions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "message", "id": "string", "conversation_id": "string", "account_id": "string", "platform": "string", "external_id": "string", "direction": "inbound", "text": "string", "sender": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "attachments": [ { "index": 1, "type": "string", "url": "https://example.com", "mime_type": "string", "filename": "string", "size": 1, "preview_url": "https://example.com", "media_id": "string", "refresh_url": "https://example.com" } ], "status": "string", "error": { "code": "string", "message": "string" }, "reactions": [ { "emoji": "string", "from_me": true, "sender_id": "string", "reacted_at": "2026-10-13T09:00:00.000Z" } ], "reply_to_id": "string", "reply_to_external_id": "string", "is_edited": true, "edited_at": "2026-10-13T09:00:00.000Z", "edit_count": 1, "edit_history": [ { "text": "string", "edited_at": "2026-10-13T09:00:00.000Z" } ], "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "sent_via": "string", "sent_by_user_id": "string", "sent_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z", "read_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Resolve a message attachment `GET /inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}` A media URL that works now: re-mints expired Instagram / Messenger URLs, downloads X DM media. format=redirect (default) answers 302; format=json returns the URL. Access: `read` · MCP tool: `get-message-attachment` · Zernio: `GET /v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}` ### Path parameters - `conversationId` (string; required; 1–80 characters): conversation id (conv_…) - `messageId` (string; required; 1–500 characters): Message id - `index` (integer; required; 0–50) ### Query parameters - `format` (string; one of redirect, json) - `account_id` (string) ```bash curl "https://api.socialit.com/v1/inbox/conversations/conv_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messages/MESSAGE_ID/attachments/INDEX" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "message_attachment", "message_id": "string", "index": 1, "type": "string", "url": "https://example.com", "mime_type": "string", "refreshed": true } ``` ## List posts with comments `GET /inbox/posts` Posts of every connected account with their comment counters, most recent comment first. Access: `read` · MCP tool: `list-inbox-posts` · Zernio: `GET /v1/inbox/comments` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of last_comment_at, published_at, comment_count) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string): Only items of this profile (pro_…) - `account_id` (string): Only items of this account (sa_…) - `platform` (string; one of facebook, instagram, x, linkedin, threads, bluesky, pinterest, tiktok, youtube, google_business, reddit, snapchat, …) - `min_comments` (integer) - `since` (string (date-time)) - `unread` (boolean) ```bash curl "https://api.socialit.com/v1/inbox/posts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "inbox_post", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "post_id": "string", "content": "string", "picture_url": "https://example.com", "permalink": "string", "published_at": "2026-10-13T09:00:00.000Z", "comment_count": 1, "unread_comment_count": 1, "like_count": 1, "last_comment_at": "2026-10-13T09:00:00.000Z", "cid": "string", "subreddit": "string", "is_ad": true, "ad_id": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a commented post `GET /inbox/posts/{postId}` Access: `read` · MCP tool: `get-inbox-post` ### Path parameters - `postId` (string; required; 1–500 characters): Inbox post id (inp_…), Socialit post id (pst_…) or the network post id (with account_id) ### Query parameters - `account_id` (string) ```bash curl "https://api.socialit.com/v1/inbox/posts/POST_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "inbox_post", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "post_id": "string", "content": "string", "picture_url": "https://example.com", "permalink": "string", "published_at": "2026-10-13T09:00:00.000Z", "comment_count": 1, "unread_comment_count": 1, "like_count": 1, "last_comment_at": "2026-10-13T09:00:00.000Z", "cid": "string", "subreddit": "string", "is_ad": true, "ad_id": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List a post's comments `GET /inbox/posts/{postId}/comments` Comments of one post, fetched from the network (default) and stored. comment_id lists that comment's replies. Access: `read` · MCP tool: `list-post-comments` · Zernio: `GET /v1/inbox/comments/{postId}` ### Path parameters - `postId` (string; required; 1–500 characters): Inbox post id (inp_…), Socialit post id (pst_…) or the network post id (with account_id) ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of commented_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `account_id` (string) - `comment_id` (string): Only replies of this comment (cmt_… or network id) - `subreddit` (string) - `refresh` (boolean): Fetch from the network first (default true) ```bash curl "https://api.socialit.com/v1/inbox/posts/POST_ID/comments" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Comment on a post or reply to a comment `POST /inbox/posts/{postId}/comments` Access: `write` · MCP tool: `create-comment` · Zernio: `POST /v1/inbox/comments/{postId}` ### Path parameters - `postId` (string; required; 1–500 characters): Inbox post id (inp_…), Socialit post id (pst_…) or the network post id (with account_id) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string) - `text` (string; required; 1–10000 characters) - `comment_id` (string): Reply to this comment (cmt_… or network id) - `attachment_url` (string (uri)) - `media_ids` (array of string; ≤ 10 items) - `parent_cid` (string) - `root_uri` (string) - `root_cid` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/posts/POST_ID/comments" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "string", "text": "string", "comment_id": "string", "attachment_url": "https://example.com", "media_ids": [ "med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ] }' ``` Response 201: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Like a post `POST /inbox/posts/{postId}/like` Like (or react to) a post as any connected account, including posts of other accounts (LinkedIn, X, Facebook, YouTube, Bluesky, Instagram). Access: `write` · MCP tool: `like-post` · Zernio: `POST /v1/inbox/posts/{postId}/like` ### Path parameters - `postId` (string; required; 1–500 characters): Inbox post id (inp_…), Socialit post id (pst_…) or the network post id (with account_id) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `reaction_type` (string; one of LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT) - `cid` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/posts/POST_ID/like" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "reaction_type": "LIKE", "cid": "string" }' ``` Response 200: ```json { "object": "post_like", "post_id": "string", "external_post_id": "string", "account_id": "string", "liked": true, "like_uri": "string", "already_reacted": true, "reaction_type": "string" } ``` ## Unlike a post `DELETE /inbox/posts/{postId}/like` Access: `write` · MCP tool: `unlike-post` · Zernio: `DELETE /v1/inbox/posts/{postId}/like` ### Path parameters - `postId` (string; required; 1–500 characters): Inbox post id (inp_…), Socialit post id (pst_…) or the network post id (with account_id) ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `like_uri` (string) ```bash curl -X DELETE "https://api.socialit.com/v1/inbox/posts/POST_ID/like?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "post_like", "post_id": "string", "external_post_id": "string", "account_id": "string", "liked": true, "like_uri": "string", "already_reacted": true, "reaction_type": "string" } ``` ## List comments `GET /inbox/comments` Comment feed across every post (triage view): filter by read state, status, hidden, assignee, label, author. Access: `read` · MCP tool: `list-comments` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of commented_at, like_count) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string): Only items of this profile (pro_…) - `account_id` (string): Only items of this account (sa_…) - `platform` (string; one of facebook, instagram, x, linkedin, threads, bluesky, pinterest, tiktok, youtube, google_business, reddit, snapchat, …) - `inbox_post_id` (string) - `status` (string; one of open, archived) - `read` (boolean) - `hidden` (boolean) - `assignee_id` (string) - `label` (string) - `is_owner` (boolean) ```bash curl "https://api.socialit.com/v1/inbox/comments" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a comment `GET /inbox/comments/{commentId}` Access: `read` · MCP tool: `get-comment` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Query parameters - `account_id` (string) - `like_uri` (string) - `post_id` (string) ```bash curl "https://api.socialit.com/v1/inbox/comments/COMMENT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Edit or triage a comment `PATCH /inbox/comments/{commentId}` text edits the comment on the network (Reddit, and own comments on Facebook / YouTube / LinkedIn); read, status, assignee_id, labels are Socialit triage fields. Access: `write` · MCP tool: `update-comment` · Zernio: `PATCH /v1/inbox/comments/{postId}/{commentId}` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Body - `text` (string; 1–10000 characters) - `content` (string; 1–10000 characters) - `read` (boolean) - `status` (string; one of open, archived) - `assignee_id` (string | null) - `labels` (array of string; ≤ 20 items) - `account_id` (string) - `platform` (string): Ignored (Zernio compatibility) ```bash curl -X PATCH "https://api.socialit.com/v1/inbox/comments/COMMENT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "string", "content": "string", "read": true, "status": "open", "assignee_id": "string" }' ``` Response 200: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a comment `DELETE /inbox/comments/{commentId}` Access: `write` · MCP tool: `delete-comment` · Zernio: `DELETE /v1/inbox/comments/{postId}` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Query parameters - `account_id` (string) - `like_uri` (string) - `post_id` (string) ```bash curl -X DELETE "https://api.socialit.com/v1/inbox/comments/COMMENT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "comment", "id": "string", "deleted": true } ``` ## Reply to a comment `POST /inbox/comments/{commentId}/replies` Access: `write` · MCP tool: `reply-to-comment` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `text` (string; required; 1–10000 characters) - `attachment_url` (string (uri)) - `media_ids` (array of string; ≤ 10 items) - `account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/comments/COMMENT_ID/replies" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "text": "string", "attachment_url": "https://example.com", "media_ids": [ "med_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" ], "account_id": "string" }' ``` Response 201: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Set comment moderation status `POST /inbox/comments/{commentId}/moderation` YouTube: publish, reject or hold a comment for review, optionally banning the author. Access: `write` · MCP tool: `set-comment-moderation` · Zernio: `POST /v1/inbox/comments/{postId}/{commentId}/moderation` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `moderation_status` (string; required; one of published, rejected, held_for_review, heldForReview) - `ban_author` (boolean) - `account_id` (string) - `platform` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/comments/COMMENT_ID/moderation" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "moderation_status": "published", "ban_author": true, "account_id": "string", "platform": "string" }' ``` Response 200: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Hide a comment `POST /inbox/comments/{commentId}/hide` Access: `write` · MCP tool: `hide-comment` · Zernio: `POST /v1/inbox/comments/{postId}/{commentId}/hide` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string) - `post_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/comments/COMMENT_ID/hide" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "string", "post_id": "string" }' ``` Response 200: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Unhide a comment `DELETE /inbox/comments/{commentId}/hide` Access: `write` · MCP tool: `unhide-comment` · Zernio: `DELETE /v1/inbox/comments/{postId}/{commentId}/hide` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Query parameters - `account_id` (string) - `like_uri` (string) - `post_id` (string) ```bash curl -X DELETE "https://api.socialit.com/v1/inbox/comments/COMMENT_ID/hide" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Pin a comment `POST /inbox/comments/{commentId}/pin` Access: `write` · MCP tool: `pin-comment` · Zernio: `POST /v1/inbox/comments/{postId}/{commentId}/pin` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string) - `post_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/comments/COMMENT_ID/pin" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "string", "post_id": "string" }' ``` Response 200: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Unpin a comment `DELETE /inbox/comments/{commentId}/pin` Access: `write` · MCP tool: `unpin-comment` · Zernio: `DELETE /v1/inbox/comments/{postId}/{commentId}/pin` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Query parameters - `account_id` (string) - `like_uri` (string) - `post_id` (string) ```bash curl -X DELETE "https://api.socialit.com/v1/inbox/comments/COMMENT_ID/pin" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Like a comment `POST /inbox/comments/{commentId}/like` Access: `write` · MCP tool: `like-comment` · Zernio: `POST /v1/inbox/comments/{postId}/{commentId}/like` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string) - `reaction_type` (string; one of LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT) - `cid` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/comments/COMMENT_ID/like" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "string", "reaction_type": "LIKE", "cid": "string" }' ``` Response 200: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Unlike a comment `DELETE /inbox/comments/{commentId}/like` Access: `write` · MCP tool: `unlike-comment` · Zernio: `DELETE /v1/inbox/comments/{postId}/{commentId}/like` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Query parameters - `account_id` (string) - `like_uri` (string) - `post_id` (string) ```bash curl -X DELETE "https://api.socialit.com/v1/inbox/comments/COMMENT_ID/like" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "comment", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "inbox_post_id": "string", "post_id": "string", "external_post_id": "string", "external_id": "string", "parent_id": "string", "external_parent_id": "string", "is_reply": true, "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string", "is_owner": true }, "text": "string", "attachments": [ { "type": "string", "url": "https://example.com" } ], "like_count": 1, "reply_count": 1, "is_hidden": true, "is_pinned": true, "is_liked": true, "like_uri": "string", "cid": "string", "moderation_status": "string", "is_edited": true, "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "can_reply": true, "can_delete": true, "can_hide": true, "can_like": true, "url": "https://example.com", "commented_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Send a private reply `POST /inbox/comments/{commentId}/private-reply` Direct-message the author of a comment (Facebook, Instagram; one reply per comment within 7 days). Access: `write` · MCP tool: `send-private-reply` · Zernio: `POST /v1/inbox/comments/{postId}/{commentId}/private-reply` ### Path parameters - `commentId` (string; required; 1–500 characters): Comment id (cmt_…) or the network comment id (with account_id) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `text` (string; required; 1–2000 characters) - `quick_replies` (array of object; ≤ 13 items) - `quick_replies[].title` (string; required; 1–20 characters) - `quick_replies[].payload` (string; required; ≤ 1000 characters) - `quick_replies[].image_url` (string) - `buttons` (array of object; ≤ 3 items) - `buttons[].type` (string; required; one of url, postback, phone) - `buttons[].title` (string; required; 1–20 characters) - `buttons[].url` (string) - `buttons[].payload` (string) - `buttons[].phone` (string) - `account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/comments/COMMENT_ID/private-reply" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "text": "string", "quick_replies": [ { "title": "string", "payload": "string" } ], "buttons": [ { "type": "url", "title": "string" } ], "account_id": "string" }' ``` Response 201: ```json { "object": "message", "id": "string", "conversation_id": "string", "account_id": "string", "platform": "string", "external_id": "string", "direction": "inbound", "text": "string", "sender": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "attachments": [ { "index": 1, "type": "string", "url": "https://example.com", "mime_type": "string", "filename": "string", "size": 1, "preview_url": "https://example.com", "media_id": "string", "refresh_url": "https://example.com" } ], "status": "string", "error": { "code": "string", "message": "string" }, "reactions": [ { "emoji": "string", "from_me": true, "sender_id": "string", "reacted_at": "2026-10-13T09:00:00.000Z" } ], "reply_to_id": "string", "reply_to_external_id": "string", "is_edited": true, "edited_at": "2026-10-13T09:00:00.000Z", "edit_count": 1, "edit_history": [ { "text": "string", "edited_at": "2026-10-13T09:00:00.000Z" } ], "is_deleted": true, "deleted_at": "2026-10-13T09:00:00.000Z", "sent_via": "string", "sent_by_user_id": "string", "sent_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z", "read_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List reviews `GET /inbox/reviews` Facebook recommendations and Google Business reviews, newest first, with a rating summary. Access: `read` · MCP tool: `list-reviews` · Zernio: `GET /v1/inbox/reviews` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of reviewed_at, rating) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string): Only items of this profile (pro_…) - `account_id` (string): Only items of this account (sa_…) - `platform` (string; one of facebook, instagram, x, linkedin, threads, bluesky, pinterest, tiktok, youtube, google_business, reddit, snapchat, …) - `min_rating` (integer; 1–5) - `max_rating` (integer; 1–5) - `has_reply` (boolean) - `status` (string; one of open, archived) - `read` (boolean) - `refresh` (boolean): Fetch the latest reviews from the networks first ```bash curl "https://api.socialit.com/v1/inbox/reviews" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "review", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "location_id": "string", "location_name": "string", "reviewer": { "id": "string", "name": "string", "avatar_url": "https://example.com" }, "rating": 1, "recommendation": "string", "text": "string", "photos": [ { "url": "https://example.com" } ], "has_reply": true, "reply": { "external_id": "string", "text": "string", "replied_at": "2026-10-13T09:00:00.000Z" }, "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "url": "https://example.com", "reviewed_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "summary": { "total_reviews": 1, "average_rating": 1.5 } } ``` ## Get a review `GET /inbox/reviews/{reviewId}` Access: `read` · MCP tool: `get-review` ### Path parameters - `reviewId` (string; required; 1–500 characters): Review id (rev_…) or the network review id (with account_id) ### Query parameters - `account_id` (string) ```bash curl "https://api.socialit.com/v1/inbox/reviews/REVIEW_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "review", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "location_id": "string", "location_name": "string", "reviewer": { "id": "string", "name": "string", "avatar_url": "https://example.com" }, "rating": 1, "recommendation": "string", "text": "string", "photos": [ { "url": "https://example.com" } ], "has_reply": true, "reply": { "external_id": "string", "text": "string", "replied_at": "2026-10-13T09:00:00.000Z" }, "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "url": "https://example.com", "reviewed_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Triage a review `PATCH /inbox/reviews/{reviewId}` Access: `write` · MCP tool: `update-review` ### Path parameters - `reviewId` (string; required; 1–500 characters): Review id (rev_…) or the network review id (with account_id) ### Body - `read` (boolean) - `status` (string; one of open, archived) - `assignee_id` (string | null) - `labels` (array of string; ≤ 20 items) ```bash curl -X PATCH "https://api.socialit.com/v1/inbox/reviews/REVIEW_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "read": true, "status": "open", "assignee_id": "string", "labels": [ "string" ] }' ``` Response 200: ```json { "object": "review", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "location_id": "string", "location_name": "string", "reviewer": { "id": "string", "name": "string", "avatar_url": "https://example.com" }, "rating": 1, "recommendation": "string", "text": "string", "photos": [ { "url": "https://example.com" } ], "has_reply": true, "reply": { "external_id": "string", "text": "string", "replied_at": "2026-10-13T09:00:00.000Z" }, "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "url": "https://example.com", "reviewed_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Reply to a review `POST /inbox/reviews/{reviewId}/reply` Post (or replace) the public reply to a review. Access: `write` · MCP tool: `reply-to-review` · Zernio: `POST /v1/inbox/reviews/{reviewId}/reply` ### Path parameters - `reviewId` (string; required; 1–500 characters): Review id (rev_…) or the network review id (with account_id) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `text` (string; required; 1–4096 characters) - `account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/reviews/REVIEW_ID/reply" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "text": "string", "account_id": "string" }' ``` Response 200: ```json { "object": "review", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "location_id": "string", "location_name": "string", "reviewer": { "id": "string", "name": "string", "avatar_url": "https://example.com" }, "rating": 1, "recommendation": "string", "text": "string", "photos": [ { "url": "https://example.com" } ], "has_reply": true, "reply": { "external_id": "string", "text": "string", "replied_at": "2026-10-13T09:00:00.000Z" }, "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "url": "https://example.com", "reviewed_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a review reply `DELETE /inbox/reviews/{reviewId}/reply` Access: `write` · MCP tool: `delete-review-reply` · Zernio: `DELETE /v1/inbox/reviews/{reviewId}/reply` ### Path parameters - `reviewId` (string; required; 1–500 characters): Review id (rev_…) or the network review id (with account_id) ### Query parameters - `account_id` (string) ```bash curl -X DELETE "https://api.socialit.com/v1/inbox/reviews/REVIEW_ID/reply" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "review", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "location_id": "string", "location_name": "string", "reviewer": { "id": "string", "name": "string", "avatar_url": "https://example.com" }, "rating": 1, "recommendation": "string", "text": "string", "photos": [ { "url": "https://example.com" } ], "has_reply": true, "reply": { "external_id": "string", "text": "string", "replied_at": "2026-10-13T09:00:00.000Z" }, "status": "open", "read": true, "assignee_id": "string", "labels": [ "string" ], "url": "https://example.com", "reviewed_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List mentions `GET /inbox/mentions` Access: `read` · MCP tool: `list-mentions` · Zernio: `GET /v1/inbox/mentions` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of mentioned_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string): Only items of this profile (pro_…) - `account_id` (string): Only items of this account (sa_…) - `platform` (string; one of facebook, instagram, x, linkedin, threads, bluesky, pinterest, tiktok, youtube, google_business, reddit, snapchat, …) - `kind` (string; one of post, comment, caption, story, reply, quote, tag) - `read` (boolean) - `status` (string; one of open, archived) ```bash curl "https://api.socialit.com/v1/inbox/mentions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "mention", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "kind": "string", "text": "string", "permalink": "string", "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "media_id": "string", "comment_id": "string", "replied": true, "status": "open", "read": true, "mentioned_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a mention `GET /inbox/mentions/{mentionId}` Access: `read` · MCP tool: `get-mention` ### Path parameters - `mentionId` (string; required; 1–80 characters): Mention id (mtn_…) ```bash curl "https://api.socialit.com/v1/inbox/mentions/mtn_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "mention", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "kind": "string", "text": "string", "permalink": "string", "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "media_id": "string", "comment_id": "string", "replied": true, "status": "open", "read": true, "mentioned_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Triage a mention `PATCH /inbox/mentions/{mentionId}` Access: `write` · MCP tool: `update-mention` ### Path parameters - `mentionId` (string; required; 1–80 characters): Mention id (mtn_…) ### Body - `read` (boolean) - `status` (string; one of open, archived) ```bash curl -X PATCH "https://api.socialit.com/v1/inbox/mentions/mtn_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "read": true, "status": "open" }' ``` Response 200: ```json { "object": "mention", "id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "account": { "id": "string", "platform": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_id": "string" }, "external_id": "string", "kind": "string", "text": "string", "permalink": "string", "author": { "id": "string", "name": "string", "username": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "media_id": "string", "comment_id": "string", "replied": true, "status": "open", "read": true, "mentioned_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Reply to a mention `POST /inbox/mentions/reply` Reply to a stored mention (mention_id) or to an Instagram media / comment mention (account_id + media_id [+ comment_id]). Access: `write` · MCP tool: `reply-to-mention` · Zernio: `POST /v1/inbox/mentions/reply` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `text` (string; required; 1–2200 characters) - `mention_id` (string) - `account_id` (string) - `media_id` (string) - `comment_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/inbox/mentions/reply" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "text": "string", "mention_id": "string", "account_id": "string", "media_id": "string", "comment_id": "string" }' ``` Response 201: ```json { "object": "mention_reply", "id": "string", "mention_id": "string", "account_id": "string", "media_id": "string", "comment_id": "string" } ``` ## Inbox counters `GET /inbox/counts` Unread / open counters for badges. Access: `read` · MCP tool: `get-inbox-counts` ### Query parameters - `profile_id` (string) - `account_id` (string) ```bash curl "https://api.socialit.com/v1/inbox/counts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "inbox_counts", "conversations": { "open": 1, "unread": 1, "unassigned": 1, "requests": 1 }, "comments": { "unread": 1 }, "reviews": { "unread": 1, "unanswered": 1 }, "mentions": { "unread": 1 } } ``` ## Sync the inbox now `POST /inbox/sync` Queue an immediate pull from the networks that are polled (Reddit, YouTube, Bluesky, Mastodon, X, Threads, LinkedIn, Google Business, Facebook reviews, TikTok mentions). Access: `write` · MCP tool: `sync-inbox` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string) - `kinds` (array of string; unique) ```bash curl -X POST "https://api.socialit.com/v1/inbox/sync" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "string", "kinds": [ "conversations" ] }' ``` Response 202: ```json { "object": "inbox_sync", "queued": 1, "accounts": [ "string" ], "kinds": [ "string" ] } ``` ## Get persistent menu `GET /accounts/{accountId}/messenger-menu` Read the persistent menu of a Facebook or Instagram account. Access: `read` · MCP tool: `get-messenger-menu` · Zernio: `GET /v1/accounts/{accountId}/messenger-menu` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-menu" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "messenger_menu", "account_id": "string", "persistent_menu": [ {} ] } ``` ## Set persistent menu `PATCH /accounts/{accountId}/messenger-menu` Replace the persistent menu of a Facebook or Instagram account. Access: `write` · MCP tool: `set-messenger-menu` · Zernio: `PUT /v1/accounts/{accountId}/messenger-menu` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Body - `persistent_menu` (array of object; required; ≥ 1 items) - `persistent_menu[].locale` (string) - `persistent_menu[].composer_input_disabled` (boolean) - `persistent_menu[].call_to_actions` (array of object; required; 1–20 items) - `persistent_menu[].call_to_actions[].type` (string; one of postback, web_url, nested) - `persistent_menu[].call_to_actions[].title` (string; 1–30 characters) - `persistent_menu[].call_to_actions[].payload` (string; ≤ 1000 characters) - `persistent_menu[].call_to_actions[].url` (string; ≤ 2000 characters) - `persistent_menu[].call_to_actions[].webview_height_ratio` (string) - `persistent_menu[].call_to_actions[].call_to_actions` (array of object; ≤ 5 items) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-menu" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "persistent_menu": [ { "locale": "default", "call_to_actions": [ { "type": "postback", "title": "string" } ] } ] }' ``` Response 200: ```json { "object": "messenger_menu", "account_id": "string", "persistent_menu": [ {} ] } ``` ## Delete persistent menu `DELETE /accounts/{accountId}/messenger-menu` Remove the persistent menu from a Facebook or Instagram account. Access: `write` · MCP tool: `delete-messenger-menu` · Zernio: `DELETE /v1/accounts/{accountId}/messenger-menu` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-menu" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "messenger_menu", "id": "string", "deleted": true } ``` ## Get Messenger Get Started button `GET /accounts/{accountId}/messenger-get-started` Read the Messenger Get Started button of a Facebook account. Access: `read` · MCP tool: `get-messenger-get-started` · Zernio: `GET /v1/accounts/{accountId}/messenger-get-started` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-get-started" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "messenger_get_started", "account_id": "string", "payload": "string" } ``` ## Set Messenger Get Started button `PATCH /accounts/{accountId}/messenger-get-started` Replace the Messenger Get Started button of a Facebook account. Access: `write` · MCP tool: `set-messenger-get-started` · Zernio: `PUT /v1/accounts/{accountId}/messenger-get-started` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Body - `payload` (string; required; 1–1000 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-get-started" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "payload": "string" }' ``` Response 200: ```json { "object": "messenger_get_started", "account_id": "string", "payload": "string" } ``` ## Delete Messenger Get Started button `DELETE /accounts/{accountId}/messenger-get-started` Remove the Messenger Get Started button from a Facebook account. Access: `write` · MCP tool: `delete-messenger-get-started` · Zernio: `DELETE /v1/accounts/{accountId}/messenger-get-started` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-get-started" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "messenger_get_started", "id": "string", "deleted": true } ``` ## Get Messenger greeting text `GET /accounts/{accountId}/messenger-greeting` Read the Messenger greeting text of a Facebook account. Access: `read` · MCP tool: `get-messenger-greeting` · Zernio: `GET /v1/accounts/{accountId}/messenger-greeting` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-greeting" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "messenger_greeting", "account_id": "string", "greeting": [ { "locale": "en", "text": "string" } ] } ``` ## Set Messenger greeting text `PATCH /accounts/{accountId}/messenger-greeting` Replace the Messenger greeting text of a Facebook account. Access: `write` · MCP tool: `set-messenger-greeting` · Zernio: `PUT /v1/accounts/{accountId}/messenger-greeting` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Body - `greeting` (array of object; required; ≥ 1 items) - `greeting[].locale` (string; required; ≥ 1 characters) - `greeting[].text` (string; required; 1–160 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-greeting" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "greeting": [ { "locale": "en", "text": "string" } ] }' ``` Response 200: ```json { "object": "messenger_greeting", "account_id": "string", "greeting": [ { "locale": "en", "text": "string" } ] } ``` ## Delete Messenger greeting text `DELETE /accounts/{accountId}/messenger-greeting` Remove the Messenger greeting text from a Facebook account. Access: `write` · MCP tool: `delete-messenger-greeting` · Zernio: `DELETE /v1/accounts/{accountId}/messenger-greeting` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-greeting" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "messenger_greeting", "id": "string", "deleted": true } ``` ## Get Messenger ice breakers `GET /accounts/{accountId}/messenger-ice-breakers` Read the Messenger ice breakers of a Facebook account. Access: `read` · MCP tool: `get-messenger-ice-breakers` · Zernio: `GET /v1/accounts/{accountId}/messenger-ice-breakers` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-ice-breakers" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "messenger_ice_breakers", "account_id": "string", "ice_breakers": [ { "locale": "en", "call_to_actions": [ { "question": "string", "payload": "string" } ] } ] } ``` ## Set Messenger ice breakers `PATCH /accounts/{accountId}/messenger-ice-breakers` Replace the Messenger ice breakers of a Facebook account. Access: `write` · MCP tool: `set-messenger-ice-breakers` · Zernio: `PUT /v1/accounts/{accountId}/messenger-ice-breakers` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Body - `ice_breakers` (array of object; required; ≥ 1 items) - `ice_breakers[].locale` (string; required; ≥ 1 characters) - `ice_breakers[].call_to_actions` (array of object; required; 1–4 items) - `ice_breakers[].call_to_actions[].question` (string; required; 1–80 characters) - `ice_breakers[].call_to_actions[].payload` (string; required; 1–1000 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-ice-breakers" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ice_breakers": [ { "locale": "en", "call_to_actions": [ { "question": "string", "payload": "string" } ] } ] }' ``` Response 200: ```json { "object": "messenger_ice_breakers", "account_id": "string", "ice_breakers": [ { "locale": "en", "call_to_actions": [ { "question": "string", "payload": "string" } ] } ] } ``` ## Delete Messenger ice breakers `DELETE /accounts/{accountId}/messenger-ice-breakers` Remove the Messenger ice breakers from a Facebook account. Access: `write` · MCP tool: `delete-messenger-ice-breakers` · Zernio: `DELETE /v1/accounts/{accountId}/messenger-ice-breakers` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/messenger-ice-breakers" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "messenger_ice_breakers", "id": "string", "deleted": true } ``` ## Get Instagram ice breakers `GET /accounts/{accountId}/instagram-ice-breakers` Read the Instagram ice breakers of a Instagram account. Access: `read` · MCP tool: `get-instagram-ice-breakers` · Zernio: `GET /v1/accounts/{accountId}/instagram-ice-breakers` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram-ice-breakers" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "instagram_ice_breakers", "account_id": "string", "ice_breakers": [ { "question": "string", "payload": "string" } ] } ``` ## Set Instagram ice breakers `PATCH /accounts/{accountId}/instagram-ice-breakers` Replace the Instagram ice breakers of a Instagram account. Access: `write` · MCP tool: `set-instagram-ice-breakers` · Zernio: `PUT /v1/accounts/{accountId}/instagram-ice-breakers` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Body - `ice_breakers` (array of object; required; 1–4 items) - `ice_breakers[].question` (string; required; 1–80 characters) - `ice_breakers[].payload` (string; required; 1–1000 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram-ice-breakers" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ice_breakers": [ { "question": "string", "payload": "string" } ] }' ``` Response 200: ```json { "object": "instagram_ice_breakers", "account_id": "string", "ice_breakers": [ { "question": "string", "payload": "string" } ] } ``` ## Delete Instagram ice breakers `DELETE /accounts/{accountId}/instagram-ice-breakers` Remove the Instagram ice breakers from a Instagram account. Access: `write` · MCP tool: `delete-instagram-ice-breakers` · Zernio: `DELETE /v1/accounts/{accountId}/instagram-ice-breakers` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram-ice-breakers" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "instagram_ice_breakers", "id": "string", "deleted": true } ``` ## Repost (retweet) a post on X `POST /accounts/{accountId}/x/retweets` Access: `write` · MCP tool: `retweet` · Zernio: `POST /v1/twitter/retweet` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `tweet_id` (string; required; 1–300 characters) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/x/retweets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "tweet_id": "string" }' ``` Response 200: ```json { "object": "x_retweet", "account_id": "string", "tweet_id": "string", "retweeted": true } ``` ## Undo a repost on X `DELETE /accounts/{accountId}/x/retweets/{tweetId}` Access: `write` · MCP tool: `unretweet` · Zernio: `DELETE /v1/twitter/retweet` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) - `tweetId` (string; required; 1–300 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/x/retweets/TWEET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "x_retweet", "account_id": "string", "tweet_id": "string", "retweeted": true } ``` ## Bookmark a post on X `POST /accounts/{accountId}/x/bookmarks` Access: `write` · MCP tool: `bookmark-tweet` · Zernio: `POST /v1/twitter/bookmark` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `tweet_id` (string; required; 1–300 characters) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/x/bookmarks" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "tweet_id": "string" }' ``` Response 200: ```json { "object": "x_bookmark", "account_id": "string", "tweet_id": "string", "bookmarked": true } ``` ## Remove an X bookmark `DELETE /accounts/{accountId}/x/bookmarks/{tweetId}` Access: `write` · MCP tool: `remove-bookmark` · Zernio: `DELETE /v1/twitter/bookmark` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) - `tweetId` (string; required; 1–300 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/x/bookmarks/TWEET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "x_bookmark", "account_id": "string", "tweet_id": "string", "bookmarked": true } ``` ## Follow a user on X `POST /accounts/{accountId}/x/following` Follow (or request to follow a protected account). Requires X Enterprise access: otherwise 402 enterprise_required. Access: `write` · MCP tool: `follow-x-user` · Zernio: `POST /v1/twitter/follow` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `target_user_id` (string; required; 1–64 characters) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/x/following" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "target_user_id": "string" }' ``` Response 200: ```json { "object": "x_follow", "account_id": "string", "target_user_id": "string", "following": true, "pending_follow": true } ``` ## Unfollow a user on X `DELETE /accounts/{accountId}/x/following/{targetUserId}` Access: `write` · MCP tool: `unfollow-x-user` · Zernio: `DELETE /v1/twitter/follow` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) - `targetUserId` (string; required; 1–64 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/x/following/TARGET_USER_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "x_follow", "account_id": "string", "target_user_id": "string", "following": true, "pending_follow": true } ``` ## Search recent posts on X `GET /accounts/{accountId}/x/search` Posts from the last 7 days matching an X search query (operators passed through). Access: `read` · MCP tool: `search-tweets` · Zernio: `GET /v1/twitter/search` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Query parameters - `query` (string; required; 1–512 characters) - `limit` (integer; 10–100) - `since_id` (string; pattern ^[0-9]+$) - `until_id` (string; pattern ^[0-9]+$) - `start_time` (string (date-time)) - `end_time` (string (date-time)) - `cursor` (string) - `sort_order` (string; one of recency, relevancy) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/x/search?query=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "tweet", "id": "string", "text": "string", "created_at": "2026-10-13T09:00:00.000Z", "conversation_id": "string", "in_reply_to_tweet_id": "string", "lang": "string", "author": { "id": "string", "username": "string", "name": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "like_count": 1, "reply_count": 1, "retweet_count": 1, "quote_count": 1, "url": "https://example.com" } ], "limit": 1, "has_more": true, "next_cursor": "string", "previous_cursor": "string", "meta": { "result_count": 1, "newest_id": "string", "oldest_id": "string" } } ``` ## Look up a post on X `GET /accounts/{accountId}/x/tweets/{tweetId}` tweetId is the numeric id or a URL-encoded post URL. Access: `read` · MCP tool: `get-tweet` · Zernio: `GET /v1/twitter/tweet` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) - `tweetId` (string; required; 1–300 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/x/tweets/TWEET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "tweet", "id": "string", "text": "string", "created_at": "2026-10-13T09:00:00.000Z", "conversation_id": "string", "in_reply_to_tweet_id": "string", "lang": "string", "author": { "id": "string", "username": "string", "name": "string", "avatar_url": "https://example.com", "verified_type": "string" }, "like_count": 1, "reply_count": 1, "retweet_count": 1, "quote_count": 1, "url": "https://example.com" } ``` ## Search Reddit posts `GET /accounts/{accountId}/reddit/search` Access: `read` · MCP tool: `search-reddit` · Zernio: `GET /v1/reddit/search` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Query parameters - `q` (string; required; 1–512 characters) - `subreddit` (string; ≤ 100 characters) - `restrict_sr` (boolean) - `sort` (string; one of relevance, hot, top, new, comments) - `t` (string; one of hour, day, week, month, year, all) - `limit` (integer; 1–100) - `after` (string) - `cursor` (string) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reddit/search?q=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "reddit_post", "id": "string", "fullname": "string", "title": "string", "author": "string", "subreddit": "string", "url": "https://example.com", "permalink": "string", "selftext": "string", "created_at": "2026-10-13T09:00:00.000Z", "score": 1, "num_comments": 1, "over_18": true, "stickied": true, "flair_text": "string", "is_gallery": true, "gallery_images": [ "string" ] } ], "limit": 1, "has_more": true, "next_cursor": "string", "previous_cursor": "string" } ``` ## Get a subreddit feed `GET /accounts/{accountId}/reddit/feed` Access: `read` · MCP tool: `get-reddit-feed` · Zernio: `GET /v1/reddit/feed` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Query parameters - `subreddit` (string; ≤ 100 characters) - `sort` (string; one of hot, new, top, rising) - `t` (string; one of hour, day, week, month, year, all) - `limit` (integer; 1–100) - `after` (string) - `cursor` (string) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reddit/feed" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "reddit_post", "id": "string", "fullname": "string", "title": "string", "author": "string", "subreddit": "string", "url": "https://example.com", "permalink": "string", "selftext": "string", "created_at": "2026-10-13T09:00:00.000Z", "score": 1, "num_comments": 1, "over_18": true, "stickied": true, "flair_text": "string", "is_gallery": true, "gallery_images": [ "string" ] } ], "limit": 1, "has_more": true, "next_cursor": "string", "previous_cursor": "string" } ``` ## Get a Reddit post's comments `GET /accounts/{accountId}/reddit/posts/{postId}/comments` Access: `read` · MCP tool: `get-reddit-post-comments` · Zernio: `GET /v1/reddit/comments/{postId}` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) - `postId` (string; required; 1–64 characters) ### Query parameters - `sort` (string; one of new, top, best, controversial, old, qa) - `limit` (integer; 1–500) - `comment_id` (string; ≤ 64 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reddit/posts/POST_ID/comments" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "reddit_comment_thread", "post": { "object": "reddit_post", "id": "string", "fullname": "string", "title": "string", "author": "string", "subreddit": "string", "url": "https://example.com", "permalink": "string", "selftext": "string", "created_at": "2026-10-13T09:00:00.000Z", "score": 1, "num_comments": 1, "over_18": true, "stickied": true, "flair_text": "string", "is_gallery": true, "gallery_images": [ "string" ] }, "data": [ { "object": "reddit_comment", "id": "string", "fullname": "string", "parent_id": "string", "author": "string", "body": "string", "permalink": "string", "created_at": "2026-10-13T09:00:00.000Z", "score": 1, "num_replies": 1, "depth": 1, "is_submitter": true, "edited": true, "stickied": true, "distinguished": "string" } ], "more": [ "string" ] } ``` --- Source: https://socialit.com/docs/api-reference/inbox/ # Analytics API > Post and account analytics, platform-native insights and inbox analytics. Dates are UTC days (YYYY-MM-DD). History is limited by the plan (free 30 d, pro 365 d, business 730 d). Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List post analytics `GET /analytics` Posts (Socialit and external) with their metrics per platform, paginated, plus an overview. Defaults to the last 90 days (max 366). Dates are UTC days (YYYY-MM-DD). History is limited by the plan (free 30 d, pro 365 d, business 730 d). Access: `read` · MCP tool: `list-post-analytics` · Zernio: `GET /v1/analytics` ### Query parameters - `page` (integer; ≥ 1) - `limit` (integer; 1–100) - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) - `source` (string; one of all, socialit, late, external): all (default), socialit (published through Socialit; alias late), external (imported) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `tags` (string; ≤ 2000 characters): Comma-separated post tags (max 20): only Socialit posts carrying every tag (exact, case-sensitive). More than 200 matching published posts in the range → 400 (narrow the dates). - `sort` (string; one of date, engagement, impressions, reach, likes, comments, shares, saves, clicks, views, engagement_rate) - `order` (string; one of asc, desc) ```bash curl "https://api.socialit.com/v1/analytics" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "post_analytics", "id": "string", "post_id": "string", "status": "string", "source": "socialit", "content": "string", "profile_id": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "platform": "string", "platform_post_url": "https://example.com", "thumbnail_url": "https://example.com", "sync_status": "synced", "calculated": true, "metrics": { "impressions": 1.5, "reach": 1.5, "views": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5 }, "platforms": [ { "object": "posting_analytics", "posting_id": "string", "account_id": "string", "account_username": "string", "platform": "string", "status": "string" } ], "last_synced_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "overview": { "total_posts": 1, "published_posts": 1, "scheduled_posts": 1, "last_synced_at": "2026-10-13T09:00:00.000Z", "stale_accounts": 1 } } ``` ## Get analytics for one post `GET /analytics/posts/{postId}` Accepts a post id (pst_…), a posting id (sp_…) or a platform post id. Returns 202 (same body) while a metrics sync is pending; one is queued automatically. Access: `read` · MCP tool: `get-post-analytics` · Zernio: `GET /v1/analytics` ### Path parameters - `postId` (string; required; 1–300 characters): Post id (pst_…), posting id (sp_…) or the platform post id ```bash curl "https://api.socialit.com/v1/analytics/posts/POST_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "post_analytics", "id": "string", "post_id": "string", "status": "string", "source": "socialit", "content": "string", "profile_id": "string", "scheduled_at": "2026-10-13T09:00:00.000Z", "published_at": "2026-10-13T09:00:00.000Z", "platform": "string", "platform_post_url": "https://example.com", "thumbnail_url": "https://example.com", "sync_status": "synced", "calculated": true, "metrics": { "impressions": 1.5, "reach": 1.5, "views": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5, "saves": 1.5, "clicks": 1.5, "quotes": 1.5, "follows": 1.5, "profile_views": 1.5, "website_clicks": 1.5, "watch_time_seconds": 1.5, "avg_view_duration_seconds": 1.5, "avg_view_percentage": 1.5, "completion_rate": 1.5, "replays": 1.5, "reposts": 1.5, "sends": 1.5, "outbound_clicks": 1.5, "pin_clicks": 1.5, "video_duration_seconds": 1.5, "earnings": 1.5, "engagements": 1.5, "engagement_rate": 1.5 }, "platforms": [ { "object": "posting_analytics", "posting_id": "string", "account_id": "string", "account_username": "string", "platform": "string", "status": "string", "platform_post_id": "string", "platform_post_url": "https://example.com", "metrics": { "impressions": 1.5, "reach": 1.5, "views": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5 }, "sync_status": "synced", "error_code": "string", "error_message": "string", "last_synced_at": "2026-10-13T09:00:00.000Z" } ], "last_synced_at": "2026-10-13T09:00:00.000Z" } ``` ## Analytics changed since a cursor `GET /analytics/delta` Cursor feed of changed post metric snapshots across every account you can read (oldest first). Call without cursor first to get the current position, load your baseline from GET /analytics, then poll with next_cursor. Cursors expire after 7 days. Access: `read` · MCP tool: `get-analytics-delta` · Zernio: `GET /v1/analytics/delta` ### Query parameters - `cursor` (string; ≤ 200 characters) - `limit` (integer; 1–100) - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" ```bash curl "https://api.socialit.com/v1/analytics/delta" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "analytics_delta", "data": [ { "object": "analytics_change", "id": "string", "post_id": "string", "posting_id": "string", "account_id": "string", "profile_id": "string", "platform": "string", "platform_post_id": "string", "published_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "is_deleted": true, "metrics": { "impressions": 1.5, "reach": 1.5, "views": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5 } } ], "next_cursor": "string", "has_more": true } ``` ## Get the daily metric history of a post `GET /analytics/post-timeline` One row per day and platform (last snapshot of the day). Defaults to the last 90 days. Access: `read` · MCP tool: `get-post-timeline` · Zernio: `GET /v1/analytics/post-timeline` ### Query parameters - `post_id` (string; required; 1–300 characters) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) ```bash curl "https://api.socialit.com/v1/analytics/post-timeline?post_id=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "post_timeline", "post_id": "string", "from_date": "string", "to_date": "string", "timeline": [ { "date": "string", "posting_id": "string", "account_id": "string", "platform": "string", "platform_post_id": "string", "metrics": { "impressions": 1.5, "reach": 1.5, "views": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5 } } ] } ``` ## Sync external posts of an account now `POST /posts/sync-external` Fetches the account's latest posts from the network (including posts published natively), imports them with their metrics and, with url or post_id, returns the matching post. Debounced per account (15 s). Access: `write` · MCP tool: `sync-external-posts` · Zernio: `POST /v1/posts/sync-external` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `url` (string; ≤ 2000 characters) - `post_id` (string; ≤ 300 characters): Platform post id ```bash curl -X POST "https://api.socialit.com/v1/posts/sync-external" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "url": "https://example.com", "post_id": "string" }' ``` Response 200: ```json { "object": "external_post_sync", "account_id": "string", "synced": { "posts_found": 1, "posts_synced": 1, "skipped": true }, "found": true, "post": { "object": "external_post", "post_id": "string", "posting_id": "string", "account_id": "string", "platform": "string", "platform_post_id": "string", "platform_post_url": "https://example.com", "content": "string", "published_at": "2026-10-13T09:00:00.000Z", "metrics": { "impressions": 1.5, "reach": 1.5, "views": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5 } }, "posts": [ { "object": "external_post", "post_id": "string", "posting_id": "string", "account_id": "string", "platform": "string", "platform_post_id": "string", "platform_post_url": "https://example.com", "content": "string", "published_at": "2026-10-13T09:00:00.000Z", "metrics": { "impressions": 1.5, "reach": 1.5, "views": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5 } } ] } ``` ## Get an analytics dashboard `GET /analytics/dashboard` Totals, follower growth, a daily series, top and recent posts in one call. Daily and total metrics use received attribution. Cross-network totals are Socialit-calculated (calculated: true) and come with a per-platform breakdown; YouTube numbers are never folded into derived rates. Pinterest analytics are never stored and are absent from stored aggregates. Access: `read` · MCP tool: `get-analytics-dashboard` · Zernio: `GET /v1/analytics/dashboard` ### Query parameters - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) - `from_date` (string; required): UTC day (YYYY-MM-DD) - `to_date` (string; required): UTC day (YYYY-MM-DD) - `compare` (string; one of previous_period) - `top_posts` (integer; 0–25) - `recent_posts` (integer; 0–25) ```bash curl "https://api.socialit.com/v1/analytics/dashboard?from_date=value&to_date=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "analytics_dashboard", "date_range": { "from_date": "string", "to_date": "string" }, "calculated": true, "totals": { "impressions": 1.5, "reach": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5, "saves": 1.5, "clicks": 1.5, "views": 1.5, "engagement": 1.5, "engagement_rate": 1.5 }, "previous_totals": { "impressions": 1.5, "reach": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5, "saves": 1.5, "clicks": 1.5, "views": 1.5, "engagement": 1.5, "engagement_rate": 1.5 }, "followers": { "current": 1.5, "gained": 1.5, "by_account": [ { "account_id": "string", "platform": "string", "current": 1.5, "gained": 1.5 } ] }, "previous_followers": { "current": 1.5, "gained": 1.5, "by_account": [ { "account_id": "string", "platform": "string", "current": 1.5, "gained": 1.5 } ] }, "daily": [ { "date": "string", "impressions": 1.5, "reach": 1.5, "engagement": 1.5, "views": 1.5, "followers_gained": 1.5 } ], "platform_breakdown": [ { "platform": "string", "posts": 1.5, "impressions": 1.5, "reach": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5, "saves": 1.5, "clicks": 1.5, "views": 1.5, "engagement": 1.5, "followers": 1.5 } ], "top_posts": [ { "post_id": "string", "posting_id": "string", "account_id": "string", "platform": "string", "content": "string", "platform_post_url": "https://example.com", "thumbnail_url": "https://example.com", "published_at": "2026-10-13T09:00:00.000Z", "metrics": { "impressions": 1.5, "reach": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5, "saves": 1.5 } } ], "recent_posts": [ { "post_id": "string", "posting_id": "string", "account_id": "string", "platform": "string", "content": "string", "platform_post_url": "https://example.com", "thumbnail_url": "https://example.com", "published_at": "2026-10-13T09:00:00.000Z", "metrics": { "impressions": 1.5, "reach": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5, "saves": 1.5 } } ], "data_as_of": "2026-10-13T09:00:00.000Z" } ``` ## Get daily aggregated metrics `GET /analytics/daily-metrics` Per-day post counts and summed metrics plus a platform breakdown. Defaults to the last 180 days. Cross-network totals are Socialit-calculated (calculated: true) and come with a per-platform breakdown; YouTube numbers are never folded into derived rates. Pinterest analytics are never stored and are absent from stored aggregates. Access: `read` · MCP tool: `get-daily-metrics` · Zernio: `GET /v1/analytics/daily-metrics` ### Query parameters - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `source` (string; one of all, socialit, late, external): all (default), socialit (published through Socialit; alias late), external (imported) - `attribution` (string; one of publish, received) ```bash curl "https://api.socialit.com/v1/analytics/daily-metrics" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "daily_metrics", "from_date": "string", "to_date": "string", "attribution": "publish", "calculated": true, "daily": [ { "date": "string", "post_count": 1, "platforms": {}, "metrics": { "impressions": 1.5, "reach": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5, "saves": 1.5 } } ], "platform_breakdown": [ { "platform": "string", "post_count": 1, "impressions": 1.5, "reach": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5, "saves": 1.5, "clicks": 1.5, "views": 1.5 } ] } ``` ## Get the best times to post `GET /analytics/best-time` Average engagement of published posts by UTC weekday (0 = Sunday) and hour, best slots first. Access: `read` · MCP tool: `get-best-time-to-post` · Zernio: `GET /v1/analytics/best-time` ### Query parameters - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `source` (string; one of all, socialit, late, external): all (default), socialit (published through Socialit; alias late), external (imported) ```bash curl "https://api.socialit.com/v1/analytics/best-time" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "best_time", "timezone": "Europe/Prague", "slots": [ { "day_of_week": 1, "hour": 1, "avg_engagement": 1.5, "post_count": 1 } ] } ``` ## Get content performance decay `GET /analytics/content-decay` Average share of a post's final engagement reached 1h, 6h, 24h, 3d, 7d and 30d after publishing. Access: `read` · MCP tool: `get-content-decay` · Zernio: `GET /v1/analytics/content-decay` ### Query parameters - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `source` (string; one of all, socialit, late, external): all (default), socialit (published through Socialit; alias late), external (imported) ```bash curl "https://api.socialit.com/v1/analytics/content-decay" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "content_decay", "buckets": [ { "bucket_order": 1, "bucket_label": "string", "avg_pct_of_final": 1.5, "post_count": 1 } ] } ``` ## Get posting frequency vs engagement `GET /analytics/posting-frequency` Average engagement rate and engagement per platform for each observed posts-per-week cadence. Access: `read` · MCP tool: `get-posting-frequency` · Zernio: `GET /v1/analytics/posting-frequency` ### Query parameters - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `source` (string; one of all, socialit, late, external): all (default), socialit (published through Socialit; alias late), external (imported) ```bash curl "https://api.socialit.com/v1/analytics/posting-frequency" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "posting_frequency", "frequency": [ { "platform": "string", "posts_per_week": 1, "avg_engagement_rate": 1.5, "avg_engagement": 1.5, "weeks_count": 1 } ] } ``` ## Get stored analytics of an account `GET /analytics/accounts/{accountId}` Daily follower snapshots and normalized daily insights collected by the analytics sync (Pinterest: live, cached for an hour). Access: `read` · MCP tool: `get-account-analytics` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Query parameters - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) ```bash curl "https://api.socialit.com/v1/analytics/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_analytics", "account_id": "string", "platform": "string", "username": "string", "date_range": { "from_date": "string", "to_date": "string" }, "current": { "followers": 1, "following": 1, "posts_count": 1, "date": "string" }, "snapshots": [ { "date": "string", "followers": 1, "following": 1, "posts_count": 1 } ], "insights": [ { "date": "string", "metrics": {} } ], "totals": { "key": 1.5 }, "last_synced_at": "2026-10-13T09:00:00.000Z", "cached": true } ``` ## Get audience demographics of an account `GET /analytics/accounts/{accountId}/demographics` Live audience demographics from the network (age, gender, country, city, locale where available). Access: `read` · MCP tool: `get-account-demographics` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Query parameters - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) ```bash curl "https://api.socialit.com/v1/analytics/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/demographics" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "demographics", "account_id": "string", "platform": "string", "metric": "string", "timeframe": "string", "video_id": "string", "title": "string", "published_at": "2026-10-13T09:00:00.000Z", "snapshot_date": "string", "date_range": { "since": "string", "until": "string" }, "demographics": { "key": [ { "dimension": "string", "value": 1.5 } ] }, "note": "string" } ``` ## Run a network analytics report `GET /analytics/accounts/{accountId}/reports/{report}` Live network-specific report (e.g. YouTube traffic sources, Pinterest top pins, Threads benchmarks). Extra query parameters are passed to the report. Access: `read` · MCP tool: `get-account-report` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) - `report` (string; required; 1–80 characters) ### Query parameters - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) ```bash curl "https://api.socialit.com/v1/analytics/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reports/REPORT" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "platform_report", "account_id": "string", "platform": "string", "report": "string", "data": {} } ``` ## Queue an analytics sync for an account `POST /analytics/accounts/{accountId}/sync` Refreshes stats, insights and post metrics in the background (202). analytics.synced fires when it completes. Access: `write` · MCP tool: `sync-account-analytics` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `scope` (array of string; ≥ 1 items, unique) ```bash curl -X POST "https://api.socialit.com/v1/analytics/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/sync" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "scope": [ "stats" ] }' ``` Response 202: ```json { "object": "analytics_sync", "account_id": "string", "status": "queued", "scope": [ "string" ], "queued_at": "2026-10-13T09:00:00.000Z" } ``` ## Get YouTube channel insights `GET /analytics/youtube/channel-insights` Channel metrics from YouTube Analytics (2-3 day delay, max 89 days). Requires the yt-analytics.readonly scope. Access: `read` · MCP tool: `get-youtube-channel-insights` · Zernio: `GET /v1/analytics/youtube/channel-insights` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `metrics` (string): Comma-separated metric names (network vocabulary) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `metric_type` (string; one of total_value, time_series) ```bash curl "https://api.socialit.com/v1/analytics/youtube/channel-insights?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_insights", "account_id": "string", "platform": "string", "date_range": { "since": "string", "until": "string" }, "metric_type": "total_value", "breakdown": "string", "metrics": { "key": { "total": 1.5, "values": [ { "date": "string", "value": 1.5 } ], "breakdowns": [ { "dimension": "string", "value": 1.5 } ], "unit": "string", "currency": "USD" } }, "unavailable_metrics": [ { "metric": "string", "reason": "string", "message": "string" } ], "data_delay": "string" } ``` ## Get YouTube daily views of a video `GET /analytics/youtube/daily-views` Daily views, watch time and subscriber changes of one video (max 90 days; default ends 3 days ago). Access: `read` · MCP tool: `get-youtube-daily-views` · Zernio: `GET /v1/analytics/youtube/daily-views` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `video_id` (string; required; 1–64 characters) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) ```bash curl "https://api.socialit.com/v1/analytics/youtube/daily-views?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd&video_id=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "youtube_daily_views", "account_id": "string", "video_id": "string", "title": "string", "duration_seconds": 1, "date_range": { "since": "string", "until": "string" }, "provisional_since": "string", "total_views": 1.5, "daily_views": [ { "date": "string", "views": 1.5, "estimated_minutes_watched": 1.5, "average_view_duration": 1.5, "average_view_percentage": 1.5, "subscribers_gained": 1.5, "subscribers_lost": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5 } ], "last_synced_at": "2026-10-13T09:00:00.000Z" } ``` ## Get the YouTube audience retention curve of a video `GET /analytics/youtube/video-retention` Access: `read` · MCP tool: `get-youtube-video-retention` · Zernio: `GET /v1/analytics/youtube/video-retention` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `video_id` (string; required; 1–64 characters) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) ```bash curl "https://api.socialit.com/v1/analytics/youtube/video-retention?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd&video_id=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "youtube_video_retention", "account_id": "string", "video_id": "string", "title": "string", "published_at": "2026-10-13T09:00:00.000Z", "duration_seconds": 1, "date_range": { "since": "string", "until": "string" }, "provisional_since": "string", "retention_curve": [ { "elapsed_video_time_ratio": 1.5, "audience_watch_ratio": 1.5, "relative_retention_performance": 1.5, "started_watching": 1.5, "stopped_watching": 1.5, "total_segment_impressions": 1.5 } ], "note": "string" } ``` ## Get YouTube audience demographics `GET /analytics/youtube/demographics` Age and gender are viewer percentages; country values are views. Channel-wide or one video with video_id. Access: `read` · MCP tool: `get-youtube-demographics` · Zernio: `GET /v1/analytics/youtube/demographics` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `video_id` (string; ≤ 64 characters) - `breakdown` (string): age,gender,country - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) ```bash curl "https://api.socialit.com/v1/analytics/youtube/demographics?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "demographics", "account_id": "string", "platform": "string", "metric": "string", "timeframe": "string", "video_id": "string", "title": "string", "published_at": "2026-10-13T09:00:00.000Z", "snapshot_date": "string", "date_range": { "since": "string", "until": "string" }, "demographics": { "key": [ { "dimension": "string", "value": 1.5 } ] }, "note": "string" } ``` ## Get LinkedIn organization analytics `GET /analytics/linkedin/org-aggregate-analytics` Share, follower and page statistics of a LinkedIn organization page (max 89 days). Access: `read` · MCP tool: `get-linkedin-org-analytics` · Zernio: `GET /v1/analytics/linkedin/org-aggregate-analytics` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `metrics` (string): Comma-separated metric names (network vocabulary) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `metric_type` (string; one of total_value, time_series) ```bash curl "https://api.socialit.com/v1/analytics/linkedin/org-aggregate-analytics?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_insights", "account_id": "string", "platform": "string", "date_range": { "since": "string", "until": "string" }, "metric_type": "total_value", "breakdown": "string", "metrics": { "key": { "total": 1.5, "values": [ { "date": "string", "value": 1.5 } ], "breakdowns": [ { "dimension": "string", "value": 1.5 } ], "unit": "string", "currency": "USD" } }, "unavailable_metrics": [ { "metric": "string", "reason": "string", "message": "string" } ], "data_delay": "string" } ``` ## Get LinkedIn personal account aggregate stats `GET /accounts/{accountId}/linkedin/aggregate-analytics` Totals or daily series across the member's posts (posts published through Socialit; LinkedIn API limitation). Access: `read` · MCP tool: `get-linkedin-aggregate-analytics` · Zernio: `GET /v1/accounts/{accountId}/linkedin-aggregate-analytics` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Query parameters - `aggregation` (string; one of TOTAL, DAILY) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `metrics` (string): IMPRESSION,MEMBERS_REACHED,REACTION,COMMENT,RESHARE,POST_SAVE,POST_SEND ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/linkedin/aggregate-analytics" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "linkedin_aggregate_analytics", "account_id": "string", "platform": "string", "account_type": "string", "username": "string", "aggregation": "TOTAL", "date_range": { "since": "string", "until": "string" }, "analytics": { "key": 1.5 }, "skipped_metrics": [ "string" ], "note": "string", "last_updated": "2026-10-13T09:00:00.000Z" } ``` ## Get LinkedIn post stats `GET /accounts/{accountId}/linkedin/post-analytics` Access: `read` · MCP tool: `get-linkedin-post-analytics` · Zernio: `GET /v1/accounts/{accountId}/linkedin-post-analytics` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Query parameters - `urn` (string; required; 1–300 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/linkedin/post-analytics?urn=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "linkedin_post_analytics", "account_id": "string", "platform": "string", "account_type": "string", "username": "string", "post_urn": "string", "analytics": { "impressions": 1.5, "reach": 1.5, "likes": 1.5, "comments": 1.5, "shares": 1.5, "saves": 1.5, "sends": 1.5, "clicks": 1.5, "views": 1.5, "engagement_rate": 1.5 }, "last_updated": "2026-10-13T09:00:00.000Z" } ``` ## Get LinkedIn post reactions `GET /accounts/{accountId}/linkedin/post-reactions` Individual reactions on an organization post (offset cursor). Access: `read` · MCP tool: `get-linkedin-post-reactions` · Zernio: `GET /v1/accounts/{accountId}/linkedin-post-reactions` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Query parameters - `urn` (string; required; 1–300 characters) - `limit` (integer; 1–100) - `cursor` (integer) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/linkedin/post-reactions?urn=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "linkedin_post_reactions", "account_id": "string", "post_urn": "string", "data": [ { "reaction_type": "string", "reaction_label": "string", "reacted_at": "2026-10-13T09:00:00.000Z", "from": { "urn": "string", "name": "string", "headline": "string", "username": "string", "profile_picture": "string", "profile_url": "https://example.com" } } ], "has_more": true, "next_cursor": "string", "total": 1, "last_updated": "2026-10-13T09:00:00.000Z" } ``` ## Get TikTok account insights `GET /analytics/tiktok/account-insights` Live counters plus daily history joined from Socialit snapshots (max 89 days). Access: `read` · MCP tool: `get-tiktok-account-insights` · Zernio: `GET /v1/analytics/tiktok/account-insights` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `metrics` (string): Comma-separated metric names (network vocabulary) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `metric_type` (string; one of total_value, time_series) ```bash curl "https://api.socialit.com/v1/analytics/tiktok/account-insights?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_insights", "account_id": "string", "platform": "string", "date_range": { "since": "string", "until": "string" }, "metric_type": "total_value", "breakdown": "string", "metrics": { "key": { "total": 1.5, "values": [ { "date": "string", "value": 1.5 } ], "breakdowns": [ { "dimension": "string", "value": 1.5 } ], "unit": "string", "currency": "USD" } }, "unavailable_metrics": [ { "metric": "string", "reason": "string", "message": "string" } ], "data_delay": "string" } ``` ## Get Facebook Page insights `GET /analytics/facebook/page-insights` Current (post-November 2025) Page metrics; followers_gained / followers_lost are synthesized from daily follows/unfollows (max 89 days). Access: `read` · MCP tool: `get-facebook-page-insights` · Zernio: `GET /v1/analytics/facebook/page-insights` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `metrics` (string): Comma-separated metric names (network vocabulary) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `metric_type` (string; one of total_value, time_series) ```bash curl "https://api.socialit.com/v1/analytics/facebook/page-insights?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_insights", "account_id": "string", "platform": "string", "date_range": { "since": "string", "until": "string" }, "metric_type": "total_value", "breakdown": "string", "metrics": { "key": { "total": 1.5, "values": [ { "date": "string", "value": 1.5 } ], "breakdowns": [ { "dimension": "string", "value": 1.5 } ], "unit": "string", "currency": "USD" } }, "unavailable_metrics": [ { "metric": "string", "reason": "string", "message": "string" } ], "data_delay": "string" } ``` ## Get lifetime monetization earnings of a Facebook post `GET /analytics/facebook/post-earnings` Lifetime (cumulative) values in the platform's raw unit; never sum across posts or dates. Access: `read` · MCP tool: `get-facebook-post-earnings` · Zernio: `GET /v1/analytics/facebook/post-earnings` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `post_id` (string; required; 1–200 characters) - `metrics` (string): Comma-separated metric names (network vocabulary) ```bash curl "https://api.socialit.com/v1/analytics/facebook/post-earnings?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd&post_id=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "post_earnings", "account_id": "string", "platform": "string", "post_id": "string", "period": "lifetime", "metrics": { "key": { "total": 1.5, "unit": "string", "currency": "USD" } }, "unavailable_metrics": [ { "metric": "string", "reason": "string", "message": "string" } ], "data_delay": "string" } ``` ## Get Facebook Page follower demographics `GET /analytics/facebook/demographics` Followers by country and city (Meta removed age and gender for Pages in November 2025). Access: `read` · MCP tool: `get-facebook-demographics` · Zernio: `GET /v1/analytics/facebook/demographics` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `breakdown` (string): country,city ```bash curl "https://api.socialit.com/v1/analytics/facebook/demographics?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "demographics", "account_id": "string", "platform": "string", "metric": "string", "timeframe": "string", "video_id": "string", "title": "string", "published_at": "2026-10-13T09:00:00.000Z", "snapshot_date": "string", "date_range": { "since": "string", "until": "string" }, "demographics": { "key": [ { "dimension": "string", "value": 1.5 } ] }, "note": "string" } ``` ## Get the reaction breakdown of a Facebook post `GET /accounts/{accountId}/facebook/post-reactions` Access: `read` · MCP tool: `get-facebook-post-reactions` · Zernio: `GET /v1/accounts/{accountId}/facebook-post-reactions` ### Path parameters - `accountId` (string; required; 1–80 characters): Account id (sa_…) ### Query parameters - `post_id` (string; required; 1–200 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/facebook/post-reactions?post_id=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "facebook_post_reactions", "account_id": "string", "platform": "string", "username": "string", "post_id": "string", "total": 1.5, "breakdown": { "like": 1.5, "love": 1.5, "haha": 1.5, "wow": 1.5, "sad": 1.5, "angry": 1.5, "care": 1.5 }, "last_updated": "2026-10-13T09:00:00.000Z" } ``` ## Get Instagram account insights `GET /analytics/instagram/account-insights` Only reach supports metric_type=time_series (Instagram API limitation). Breakdowns need metric_type=total_value. Access: `read` · MCP tool: `get-instagram-account-insights` · Zernio: `GET /v1/analytics/instagram/account-insights` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `metrics` (string): Comma-separated metric names (network vocabulary) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `metric_type` (string; one of total_value, time_series) - `breakdown` (string; one of media_product_type, follow_type, follower_type, contact_button_type) ```bash curl "https://api.socialit.com/v1/analytics/instagram/account-insights?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_insights", "account_id": "string", "platform": "string", "date_range": { "since": "string", "until": "string" }, "metric_type": "total_value", "breakdown": "string", "metrics": { "key": { "total": 1.5, "values": [ { "date": "string", "value": 1.5 } ], "breakdowns": [ { "dimension": "string", "value": 1.5 } ], "unit": "string", "currency": "USD" } }, "unavailable_metrics": [ { "metric": "string", "reason": "string", "message": "string" } ], "data_delay": "string" } ``` ## Get Instagram follower history `GET /analytics/instagram/follower-history` Daily follower count from Socialit snapshots joined with Instagram's new-follower series (max 89 days). Access: `read` · MCP tool: `get-instagram-follower-history` · Zernio: `GET /v1/analytics/instagram/follower-history` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `metrics` (string): Comma-separated metric names (network vocabulary) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `metric_type` (string; one of total_value, time_series) ```bash curl "https://api.socialit.com/v1/analytics/instagram/follower-history?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_insights", "account_id": "string", "platform": "string", "date_range": { "since": "string", "until": "string" }, "metric_type": "total_value", "breakdown": "string", "metrics": { "key": { "total": 1.5, "values": [ { "date": "string", "value": 1.5 } ], "breakdowns": [ { "dimension": "string", "value": 1.5 } ], "unit": "string", "currency": "USD" } }, "unavailable_metrics": [ { "metric": "string", "reason": "string", "message": "string" } ], "data_delay": "string" } ``` ## Get Instagram audience demographics `GET /analytics/instagram/demographics` Top 45 entries per dimension; requires at least 100 followers. Access: `read` · MCP tool: `get-instagram-demographics` · Zernio: `GET /v1/analytics/instagram/demographics` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `metric` (string; one of follower_demographics, engaged_audience_demographics) - `breakdown` (string): age,city,country,gender - `timeframe` (string; one of this_week, this_month) ```bash curl "https://api.socialit.com/v1/analytics/instagram/demographics?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "demographics", "account_id": "string", "platform": "string", "metric": "string", "timeframe": "string", "video_id": "string", "title": "string", "published_at": "2026-10-13T09:00:00.000Z", "snapshot_date": "string", "date_range": { "since": "string", "until": "string" }, "demographics": { "key": [ { "dimension": "string", "value": 1.5 } ] }, "note": "string" } ``` ## Get Instagram followers online per hour `GET /analytics/instagram/online-followers` Access: `read` · MCP tool: `get-instagram-online-followers` · Zernio: `GET /v1/analytics/instagram/online-followers` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) ```bash curl "https://api.socialit.com/v1/analytics/instagram/online-followers?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "online_followers", "account_id": "string", "platform": "string", "metric": "string", "days": [ { "end_time": "string", "hours": {} } ], "note": "string" } ``` ## Get Google Business Profile performance metrics `GET /analytics/googlebusiness/performance` Daily impressions, clicks, calls, directions, conversations, bookings and food orders (2-3 day delay, up to 18 months back). Access: `read` · MCP tool: `get-google-business-performance` · Zernio: `GET /v1/analytics/googlebusiness/performance` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `metrics` (string): Comma-separated metric names (network vocabulary) - `from_date` (string): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) ```bash curl "https://api.socialit.com/v1/analytics/googlebusiness/performance?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "account_insights", "account_id": "string", "platform": "string", "date_range": { "since": "string", "until": "string" }, "metric_type": "total_value", "breakdown": "string", "metrics": { "key": { "total": 1.5, "values": [ { "date": "string", "value": 1.5 } ], "breakdowns": [ { "dimension": "string", "value": 1.5 } ], "unit": "string", "currency": "USD" } }, "unavailable_metrics": [ { "metric": "string", "reason": "string", "message": "string" } ], "data_delay": "string" } ``` ## Get Google Business Profile search keywords `GET /analytics/googlebusiness/search-keywords` Access: `read` · MCP tool: `get-google-business-search-keywords` · Zernio: `GET /v1/analytics/googlebusiness/search-keywords` ### Query parameters - `account_id` (string; required; 1–80 characters): Account id (sa_…) - `start_month` (string; pattern ^\d{4}-\d{2}$) - `end_month` (string; pattern ^\d{4}-\d{2}$) ```bash curl "https://api.socialit.com/v1/analytics/googlebusiness/search-keywords?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "search_keywords", "account_id": "string", "platform": "string", "month_range": { "start_month": "string", "end_month": "string" }, "keywords": [ { "keyword": "string", "impressions": 1.5 } ], "note": "string" } ``` ## Get inbox messaging volume `GET /analytics/inbox/volume` Access: `read` · MCP tool: `get-inbox-volume` · Zernio: `GET /v1/analytics/inbox/volume` ### Query parameters - `from_date` (string; required): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) - `source` (string; one of human, api, workflow, sequence, broadcast, comment_automation, automation, contact, platform) ```bash curl "https://api.socialit.com/v1/analytics/inbox/volume?from_date=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "inbox_volume", "from_date": "string", "to_date": "string", "summary": { "received": 1, "sent": 1, "read": 1, "failed": 1, "unique_conversations": 1 }, "timeseries": [ { "date": "string", "received": 1, "sent": 1, "read": 1, "failed": 1 } ], "by_platform": [ { "platform": "string", "received": 1, "sent": 1, "read": 1, "failed": 1 } ] } ``` ## Get the inbox day × hour heatmap `GET /analytics/inbox/heatmap` Sparse buckets; dow is ISO (1 = Monday … 7 = Sunday), hours in UTC. Access: `read` · MCP tool: `get-inbox-heatmap` · Zernio: `GET /v1/analytics/inbox/heatmap` ### Query parameters - `from_date` (string; required): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) - `source` (string; one of human, api, workflow, sequence, broadcast, comment_automation, automation, contact, platform) - `action` (string; one of message.received, message.sent, message.read, all) ```bash curl "https://api.socialit.com/v1/analytics/inbox/heatmap?from_date=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "inbox_heatmap", "from_date": "string", "to_date": "string", "buckets": [ { "dow": 1, "hour": 1, "received": 1, "sent": 1, "read": 1 } ] } ``` ## Get inbox messages by source `GET /analytics/inbox/source-breakdown` Access: `read` · MCP tool: `get-inbox-source-breakdown` · Zernio: `GET /v1/analytics/inbox/source-breakdown` ### Query parameters - `from_date` (string; required): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) ```bash curl "https://api.socialit.com/v1/analytics/inbox/source-breakdown?from_date=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "inbox_source_breakdown", "from_date": "string", "to_date": "string", "sources": [ { "source": "string", "received": 1, "sent": 1, "read": 1, "by_platform": [ { "platform": "string", "received": 1, "sent": 1, "read": 1 } ] } ] } ``` ## Get inbox response-time stats `GET /analytics/inbox/response-time` Time to first response (each inbound streak paired with the next outbound message), summary and histogram. Access: `read` · MCP tool: `get-inbox-response-time` · Zernio: `GET /v1/analytics/inbox/response-time` ### Query parameters - `from_date` (string; required): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) ```bash curl "https://api.socialit.com/v1/analytics/inbox/response-time?from_date=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "inbox_response_time", "from_date": "string", "to_date": "string", "summary": { "sample_size": 1, "median_seconds": 1, "p90_seconds": 1, "p99_seconds": 1, "mean_seconds": 1, "fastest_seconds": 1, "slowest_seconds": 1 }, "histogram": [ { "bucket": "string", "lower_seconds": 1, "upper_seconds": 1, "count": 1 } ] } ``` ## Get top accounts by inbox volume `GET /analytics/inbox/top-accounts` Access: `read` · MCP tool: `get-inbox-top-accounts` · Zernio: `GET /v1/analytics/inbox/top-accounts` ### Query parameters - `from_date` (string; required): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) - `source` (string; one of human, api, workflow, sequence, broadcast, comment_automation, automation, contact, platform) - `limit` (integer; 1–50) ```bash curl "https://api.socialit.com/v1/analytics/inbox/top-accounts?from_date=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "inbox_top_accounts", "from_date": "string", "to_date": "string", "accounts": [ { "account_id": "string", "platform": "string", "display_name": "string", "username": "string", "received": 1, "sent": 1, "total": 1, "conversations": 1, "median_response_seconds": 1, "replied_count": 1 } ] } ``` ## List conversation analytics `GET /analytics/inbox/conversations` Access: `read` · MCP tool: `list-conversation-analytics` · Zernio: `GET /v1/analytics/inbox/conversations` ### Query parameters - `from_date` (string; required): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) - `platform` (string): Network key (x, instagram, …; aliases twitter, googlebusiness) or "all" - `profile_id` (string): Profile id (pro_…) or "all" - `account_id` (string; 1–80 characters): Account id (sa_…) - `source` (string; one of human, api, workflow, sequence, broadcast, comment_automation, automation, contact, platform) - `page` (integer; ≥ 1) - `limit` (integer; 1–100) - `sort` (string; one of last_message_at, first_message_at, total_messages, received, sent, read, failed) - `order` (string; one of asc, desc) ```bash curl "https://api.socialit.com/v1/analytics/inbox/conversations?from_date=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "conversation_analytics", "conversation_id": "string", "platform_conversation_id": "string", "account_id": "string", "platform": "string", "participant_name": "string", "participant_username": "string", "participant_picture": "string", "last_message": "string", "total_messages": 1, "received": 1, "sent": 1, "read": 1, "failed": 1, "first_message_at": "2026-10-13T09:00:00.000Z", "last_message_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "from_date": "string", "to_date": "string" } ``` ## Get analytics of one conversation `GET /analytics/inbox/conversations/{conversationId}` Access: `read` · MCP tool: `get-conversation-analytics` · Zernio: `GET /v1/analytics/inbox/conversations/{conversationId}` ### Path parameters - `conversationId` (string; required; 1–300 characters): Conversation id (conv_…) or the platform conversation id ### Query parameters - `from_date` (string; required): UTC day (YYYY-MM-DD) - `to_date` (string): UTC day (YYYY-MM-DD) ```bash curl "https://api.socialit.com/v1/analytics/inbox/conversations/CONVERSATION_ID?from_date=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "conversation_analytics_detail", "conversation_id": "string", "platform_conversation_id": "string", "platform": "string", "from_date": "string", "to_date": "string", "summary": { "received": 1, "sent": 1, "read": 1, "failed": 1, "total_messages": 1, "first_message_at": "2026-10-13T09:00:00.000Z", "last_message_at": "2026-10-13T09:00:00.000Z" }, "timeseries": [ { "date": "string", "received": 1, "sent": 1, "read": 1, "failed": 1 } ], "by_source": [ { "source": "string", "count": 1 } ] } ``` --- Source: https://socialit.com/docs/api-reference/analytics/ # Contacts API > CRM contacts: one person across platforms, linked to channels (per-account platform identities such as an Instagram or Messenger user ID). Contacts are created automatically from inbound messages; tags and custom fields feed broadcasts, sequences and workflows. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List contacts `GET /contacts` Filter with profile_id, account_id (has a channel on that account), platform, search (name, email, company), tag, tags (comma-separated, any of), is_subscribed, is_blocked, and custom fields: custom_fields..=value (conditions follow the field type; match=or applies). Access: `read` · MCP tool: `list-contacts` · Zernio: `GET /v1/contacts` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, updated_at, name, last_message_received_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string) - `account_id` (string) - `platform` (string) - `search` (string; ≤ 200 characters) - `tag` (string) - `tags` (string) - `is_subscribed` (string) - `is_blocked` (string) ```bash curl "https://api.socialit.com/v1/contacts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "contact", "id": "string", "profile_id": "string", "name": "string", "email": "you@example.com", "company": "string", "avatar_url": "https://example.com", "tags": [ "string" ], "is_subscribed": true, "is_blocked": true, "notes": "string", "custom_fields": {}, "channels": [ { "object": "contact_channel", "id": "string", "contact_id": "string", "account_id": "string", "platform": "string", "platform_identifier": "string" } ], "conversation_ids": [ "string" ], "messages_sent_count": 1, "messages_received_count": 1, "last_message_sent_at": "2026-10-13T09:00:00.000Z", "last_message_received_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a contact `POST /contacts` Optionally links a channel (account_id + platform_identifier). Phone identifiers are normalized to E.164. 409 contact_channel_exists when the identity already belongs to a contact. Access: `write` · MCP tool: `create-contact` · Zernio: `POST /v1/contacts` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string) - `name` (string; required; 1–200 characters) - `email` (string | null; ≤ 320 characters) - `company` (string | null; ≤ 200 characters) - `avatar_url` (string | null; ≤ 2048 characters) - `tags` (array of string; ≤ 100 items) - `is_subscribed` (boolean) - `notes` (string | null; ≤ 10000 characters) - `custom_fields` (object) - `account_id` (string) - `platform` (string; one of instagram, facebook, x, bluesky, reddit, discord, mastodon, tiktok, twitter) - `platform_identifier` (string; 1–255 characters) - `display_identifier` (string; ≤ 255 characters) ```bash curl -X POST "https://api.socialit.com/v1/contacts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "name": "string", "email": "you@example.com", "company": "string", "avatar_url": "https://example.com" }' ``` Response 201: ```json { "object": "contact", "id": "string", "profile_id": "string", "name": "string", "email": "you@example.com", "company": "string", "avatar_url": "https://example.com", "tags": [ "string" ], "is_subscribed": true, "is_blocked": true, "notes": "string", "custom_fields": {}, "channels": [ { "object": "contact_channel", "id": "string", "contact_id": "string", "account_id": "string", "platform": "string", "platform_identifier": "string", "display_identifier": "string", "is_subscribed": true, "conversation_id": "string", "last_active_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "messaging_window_open": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "conversation_ids": [ "string" ], "messages_sent_count": 1, "messages_received_count": 1, "last_message_sent_at": "2026-10-13T09:00:00.000Z", "last_message_received_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Bulk create contacts `POST /contacts/bulk` Up to 1000 rows. Duplicates (same channel identity, or same email in the profile) are skipped and their tags merged. Per-row errors come back in errors with HTTP 200. Access: `write` · MCP tool: `bulk-create-contacts` · Zernio: `POST /v1/contacts/bulk` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string) - `account_id` (string) - `platform` (string; one of instagram, facebook, x, bluesky, reddit, discord, mastodon, tiktok, twitter) - `contacts` (array of object; required; 1–1000 items) - `contacts[].name` (string; required; 1–200 characters) - `contacts[].platform_identifier` (string; ≤ 255 characters) - `contacts[].display_identifier` (string; ≤ 255 characters) - `contacts[].email` (string | null; ≤ 320 characters) - `contacts[].company` (string | null; ≤ 200 characters) - `contacts[].tags` (array of string; ≤ 100 items) - `contacts[].is_subscribed` (boolean) - `contacts[].custom_fields` (object) ```bash curl -X POST "https://api.socialit.com/v1/contacts/bulk" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "account_id": "string", "platform": "instagram", "contacts": [ { "name": "string", "platform_identifier": "string" } ] }' ``` Response 200: ```json { "object": "contact_bulk_result", "created": 1, "skipped": 1, "failed": 1, "total": 1, "errors": [ { "index": 1, "code": "string", "message": "string" } ], "contact_ids": [ "string" ] } ``` ## Bulk tag contacts `POST /contacts/bulk-tag` Add and/or remove tags on up to 1000 contacts. Emits contact.tag_added / contact.tag_removed per change (tag workflows start as for single updates). Unknown or inaccessible ids are listed in missing. Access: `write` · MCP tool: `bulk-tag-contacts` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `contact_ids` (array of string; required; 1–1000 items) - `add` (array of string; ≤ 100 items) - `remove` (array of string; ≤ 100 items) ### Body (one of) - Option 1 (any) - Option 2 (any) ```bash curl -X POST "https://api.socialit.com/v1/contacts/bulk-tag" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d 'null' ``` Response 200: ```json { "object": "contact_bulk_action", "action": "tag", "total": 1, "succeeded": 1, "failed": 1, "contact_ids": [ "string" ], "missing": [ "string" ] } ``` ## Bulk delete contacts `POST /contacts/bulk-delete` Delete up to 1000 contacts with their channels and field values. Emits contact.deleted for each. Unknown or inaccessible ids are listed in missing. Access: `write` · MCP tool: `bulk-delete-contacts` ### Body - `contact_ids` (array of string; required; 1–1000 items) ```bash curl -X POST "https://api.socialit.com/v1/contacts/bulk-delete" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact_ids": [ "string" ] }' ``` Response 200: ```json { "object": "contact_bulk_action", "action": "tag", "total": 1, "succeeded": 1, "failed": 1, "contact_ids": [ "string" ], "missing": [ "string" ] } ``` ## List contact tags `GET /contacts/tags` Tags in use with the number of contacts carrying each (most used first). Access: `read` · MCP tool: `list-contact-tags` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string) ```bash curl "https://api.socialit.com/v1/contacts/tags" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "contact_tag", "tag": "string", "count": 1 } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a contact `GET /contacts/{id}` Access: `read` · MCP tool: `get-contact` · Zernio: `GET /v1/contacts/{contactId}` ### Path parameters - `id` (string; required; 1–80 characters): contact id (con_…) ```bash curl "https://api.socialit.com/v1/contacts/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "contact", "id": "string", "profile_id": "string", "name": "string", "email": "you@example.com", "company": "string", "avatar_url": "https://example.com", "tags": [ "string" ], "is_subscribed": true, "is_blocked": true, "notes": "string", "custom_fields": {}, "channels": [ { "object": "contact_channel", "id": "string", "contact_id": "string", "account_id": "string", "platform": "string", "platform_identifier": "string", "display_identifier": "string", "is_subscribed": true, "conversation_id": "string", "last_active_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "messaging_window_open": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "conversation_ids": [ "string" ], "messages_sent_count": 1, "messages_received_count": 1, "last_message_sent_at": "2026-10-13T09:00:00.000Z", "last_message_received_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a contact `PATCH /contacts/{id}` tags replaces the set (emits contact.tag_added / tag_removed per change); custom_fields sets values (null clears). Unsubscribing exits sequences with exit_on_unsubscribe. Access: `write` · MCP tool: `update-contact` · Zernio: `PATCH /v1/contacts/{contactId}` ### Path parameters - `id` (string; required; 1–80 characters): contact id (con_…) ### Body - `name` (string; 1–200 characters) - `email` (string | null; ≤ 320 characters) - `company` (string | null; ≤ 200 characters) - `avatar_url` (string | null; ≤ 2048 characters) - `tags` (array of string; ≤ 100 items) - `is_subscribed` (boolean) - `notes` (string | null; ≤ 10000 characters) - `custom_fields` (object) - `is_blocked` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/contacts/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "email": "you@example.com", "company": "string", "avatar_url": "https://example.com", "tags": [ "string" ] }' ``` Response 200: ```json { "object": "contact", "id": "string", "profile_id": "string", "name": "string", "email": "you@example.com", "company": "string", "avatar_url": "https://example.com", "tags": [ "string" ], "is_subscribed": true, "is_blocked": true, "notes": "string", "custom_fields": {}, "channels": [ { "object": "contact_channel", "id": "string", "contact_id": "string", "account_id": "string", "platform": "string", "platform_identifier": "string", "display_identifier": "string", "is_subscribed": true, "conversation_id": "string", "last_active_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "messaging_window_open": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "conversation_ids": [ "string" ], "messages_sent_count": 1, "messages_received_count": 1, "last_message_sent_at": "2026-10-13T09:00:00.000Z", "last_message_received_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a contact `DELETE /contacts/{id}` Access: `write` · MCP tool: `delete-contact` · Zernio: `DELETE /v1/contacts/{contactId}` ### Path parameters - `id` (string; required; 1–80 characters): contact id (con_…) ```bash curl -X DELETE "https://api.socialit.com/v1/contacts/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "contact", "id": "string", "deleted": true } ``` ## Add or remove contact tags `POST /contacts/{id}/tags` Access: `write` · MCP tool: `update-contact-tags` ### Path parameters - `id` (string; required; 1–80 characters): contact id (con_…) ### Body - `add` (array of string; ≤ 100 items) - `remove` (array of string; ≤ 100 items) ```bash curl -X POST "https://api.socialit.com/v1/contacts/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tags" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "add": [ "string" ], "remove": [ "string" ] }' ``` Response 200: ```json { "object": "contact", "id": "string", "profile_id": "string", "name": "string", "email": "you@example.com", "company": "string", "avatar_url": "https://example.com", "tags": [ "string" ], "is_subscribed": true, "is_blocked": true, "notes": "string", "custom_fields": {}, "channels": [ { "object": "contact_channel", "id": "string", "contact_id": "string", "account_id": "string", "platform": "string", "platform_identifier": "string", "display_identifier": "string", "is_subscribed": true, "conversation_id": "string", "last_active_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "messaging_window_open": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "conversation_ids": [ "string" ], "messages_sent_count": 1, "messages_received_count": 1, "last_message_sent_at": "2026-10-13T09:00:00.000Z", "last_message_received_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List a contact's channels `GET /contacts/{id}/channels` Access: `read` · MCP tool: `list-contact-channels` · Zernio: `GET /v1/contacts/{contactId}/channels` ### Path parameters - `id` (string; required; 1–80 characters): contact id (con_…) ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR ```bash curl "https://api.socialit.com/v1/contacts/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/channels" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "contact_channel", "id": "string", "contact_id": "string", "account_id": "string", "platform": "string", "platform_identifier": "string", "display_identifier": "string", "is_subscribed": true, "conversation_id": "string", "last_active_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "messaging_window_open": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Link a channel to a contact `POST /contacts/{id}/channels` Access: `write` · MCP tool: `create-contact-channel` ### Path parameters - `id` (string; required; 1–80 characters): contact id (con_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string; required) - `platform` (string; one of instagram, facebook, x, bluesky, reddit, discord, mastodon, tiktok, twitter) - `platform_identifier` (string; required; 1–255 characters) - `display_identifier` (string; ≤ 255 characters) - `is_subscribed` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/contacts/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/channels" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "string", "platform": "instagram", "platform_identifier": "string", "display_identifier": "string", "is_subscribed": true }' ``` Response 201: ```json { "object": "contact_channel", "id": "string", "contact_id": "string", "account_id": "string", "platform": "string", "platform_identifier": "string", "display_identifier": "string", "is_subscribed": true, "conversation_id": "string", "last_active_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "messaging_window_open": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a contact channel `PATCH /contacts/{id}/channels/{channelId}` Opt a channel in or out (is_subscribed) or change its display identifier. Access: `write` · MCP tool: `update-contact-channel` ### Path parameters - `id` (string; required; 1–80 characters): contact id (con_…) - `channelId` (string; required; 1–80 characters): channel id (ch_…) ### Body - `display_identifier` (string | null; ≤ 255 characters) - `is_subscribed` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/contacts/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/channels/ch_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "display_identifier": "string", "is_subscribed": true }' ``` Response 200: ```json { "object": "contact_channel", "id": "string", "contact_id": "string", "account_id": "string", "platform": "string", "platform_identifier": "string", "display_identifier": "string", "is_subscribed": true, "conversation_id": "string", "last_active_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "messaging_window_open": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Unlink a contact channel `DELETE /contacts/{id}/channels/{channelId}` Access: `write` · MCP tool: `delete-contact-channel` ### Path parameters - `id` (string; required; 1–80 characters): contact id (con_…) - `channelId` (string; required; 1–80 characters): channel id (ch_…) ```bash curl -X DELETE "https://api.socialit.com/v1/contacts/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/channels/ch_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "contact_channel", "id": "string", "deleted": true } ``` ## Set a custom field value `PUT /contacts/{id}/fields/{slug}` The value is type-checked against the field definition (422 on mismatch). Emits contact.field_changed when the value changes. Access: `write` · MCP tool: `set-contact-field-value` · Zernio: `PUT /v1/contacts/{contactId}/fields/{slug}` ### Path parameters - `id` (string; required; 1–80 characters): contact id (con_…) - `slug` (string; required; 1–120 characters) ### Body - `value` (any; required) ```bash curl -X PUT "https://api.socialit.com/v1/contacts/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/fields/SLUG" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "value": null }' ``` Response 200: ```json { "object": "contact", "id": "string", "profile_id": "string", "name": "string", "email": "you@example.com", "company": "string", "avatar_url": "https://example.com", "tags": [ "string" ], "is_subscribed": true, "is_blocked": true, "notes": "string", "custom_fields": {}, "channels": [ { "object": "contact_channel", "id": "string", "contact_id": "string", "account_id": "string", "platform": "string", "platform_identifier": "string", "display_identifier": "string", "is_subscribed": true, "conversation_id": "string", "last_active_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "messaging_window_open": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "conversation_ids": [ "string" ], "messages_sent_count": 1, "messages_received_count": 1, "last_message_sent_at": "2026-10-13T09:00:00.000Z", "last_message_received_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Clear a custom field value `DELETE /contacts/{id}/fields/{slug}` Access: `write` · MCP tool: `clear-contact-field-value` · Zernio: `DELETE /v1/contacts/{contactId}/fields/{slug}` ### Path parameters - `id` (string; required; 1–80 characters): contact id (con_…) - `slug` (string; required; 1–120 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/contacts/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/fields/SLUG" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "contact", "id": "string", "profile_id": "string", "name": "string", "email": "you@example.com", "company": "string", "avatar_url": "https://example.com", "tags": [ "string" ], "is_subscribed": true, "is_blocked": true, "notes": "string", "custom_fields": {}, "channels": [ { "object": "contact_channel", "id": "string", "contact_id": "string", "account_id": "string", "platform": "string", "platform_identifier": "string", "display_identifier": "string", "is_subscribed": true, "conversation_id": "string", "last_active_at": "2026-10-13T09:00:00.000Z", "last_inbound_at": "2026-10-13T09:00:00.000Z", "messaging_window_open": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "conversation_ids": [ "string" ], "messages_sent_count": 1, "messages_received_count": 1, "last_message_sent_at": "2026-10-13T09:00:00.000Z", "last_message_received_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` --- Source: https://socialit.com/docs/api-reference/contacts/ # Custom Fields API > Contact custom field definitions (text, number, date, boolean, select). Slugs are unique per workspace. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List custom fields `GET /custom-fields` Access: `read` · MCP tool: `list-custom-fields` · Zernio: `GET /v1/custom-fields` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name, slug) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string) - `type` (string) ```bash curl "https://api.socialit.com/v1/custom-fields" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "custom_field", "id": "string", "profile_id": "string", "name": "string", "slug": "string", "type": "text", "options": [ "string" ], "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a custom field `POST /custom-fields` slug defaults to the name in snake_case; 409 slug_taken when used. options are required for select. Access: `write` · MCP tool: `create-custom-field` · Zernio: `POST /v1/custom-fields` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string) - `name` (string; required; 1–120 characters) - `slug` (string; 1–120 characters) - `type` (string; required; one of text, number, date, boolean, select) - `options` (array of string; ≤ 200 items) ```bash curl -X POST "https://api.socialit.com/v1/custom-fields" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "name": "string", "slug": "string", "type": "text", "options": [ "string" ] }' ``` Response 201: ```json { "object": "custom_field", "id": "string", "profile_id": "string", "name": "string", "slug": "string", "type": "text", "options": [ "string" ], "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get a custom field `GET /custom-fields/{id}` Access: `read` · MCP tool: `get-custom-field` ### Path parameters - `id` (string; required; 1–80 characters): customField id (cf_…) ```bash curl "https://api.socialit.com/v1/custom-fields/cf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "custom_field", "id": "string", "profile_id": "string", "name": "string", "slug": "string", "type": "text", "options": [ "string" ], "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a custom field `PATCH /custom-fields/{id}` Name and options only (type and slug are immutable). Access: `write` · MCP tool: `update-custom-field` · Zernio: `PATCH /v1/custom-fields/{fieldId}` ### Path parameters - `id` (string; required; 1–80 characters): customField id (cf_…) ### Body - `name` (string; 1–120 characters) - `options` (array of string; ≤ 200 items) ```bash curl -X PATCH "https://api.socialit.com/v1/custom-fields/cf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "options": [ "string" ] }' ``` Response 200: ```json { "object": "custom_field", "id": "string", "profile_id": "string", "name": "string", "slug": "string", "type": "text", "options": [ "string" ], "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a custom field `DELETE /custom-fields/{id}` Deletes the definition and every stored value. Access: `write` · MCP tool: `delete-custom-field` · Zernio: `DELETE /v1/custom-fields/{fieldId}` ### Path parameters - `id` (string; required; 1–80 characters): customField id (cf_…) ```bash curl -X DELETE "https://api.socialit.com/v1/custom-fields/cf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "custom_field", "id": "string", "deleted": true } ``` --- Source: https://socialit.com/docs/api-reference/custom-fields/ # Broadcasts API > Bulk sends to contacts on one account (Messenger / Instagram within the 24 h window or with HUMAN_AGENT, X, Bluesky…), rate limited per channel with per-recipient delivery status. Each recipient is one message. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List broadcasts `GET /broadcasts` Access: `read` · MCP tool: `list-broadcasts` · Zernio: `GET /v1/broadcasts` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, scheduled_at, name) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string) - `account_id` (string) - `status` (string) - `platform` (string) ```bash curl "https://api.socialit.com/v1/broadcasts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "broadcast", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "message": { "text": "string", "attachments": [ { "type": null, "url": null, "filename": null } ], "message_tag": "string" }, "segment_filters": { "tags": [ "string" ], "tags_match": "string", "exclude_tags": [ "string" ], "is_subscribed": true, "custom_fields": {} }, "message_preview": "string", "rate_limit_per_minute": 1, "scheduled_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "recipient_count": 1, "pending_count": 1, "sent_count": 1, "delivered_count": 1, "read_count": 1, "failed_count": 1, "skipped_count": 1, "last_error": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a broadcast draft `POST /broadcasts` segment_filters select recipients by tags, subscription and custom fields. Access: `write` · MCP tool: `create-broadcast` · Zernio: `POST /v1/broadcasts` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string) - `account_id` (string; required) - `platform` (string; one of instagram, facebook, x, bluesky, reddit, discord, mastodon, tiktok, twitter) - `name` (string; required; 1–200 characters) - `description` (string | null; ≤ 2000 characters) - `message` (object) - `message.text` (string | null; ≤ 4096 characters) - `message.attachments` (array of object; ≤ 10 items) - `message.attachments[].type` (string; one of image, video, audio, file) - `message.attachments[].url` (string; required; 1–2048 characters) - `message.attachments[].filename` (string; ≤ 255 characters) - `message.message_tag` (string | null; one of HUMAN_AGENT, CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE) - `segment_filters` (object | null) - `segment_filters.tags` (array of string; ≤ 100 items) - `segment_filters.tags_match` (string; one of any, all) - `segment_filters.exclude_tags` (array of string; ≤ 100 items) - `segment_filters.is_subscribed` (boolean) - `segment_filters.custom_fields` (object) - `rate_limit_per_minute` (integer | null; 1–6000) ```bash curl -X POST "https://api.socialit.com/v1/broadcasts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "account_id": "string", "platform": "instagram", "name": "string", "description": "string" }' ``` Response 201: ```json { "object": "broadcast", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "message": { "text": "string", "attachments": [ { "type": "string", "url": "https://example.com", "filename": "string" } ], "message_tag": "string" }, "segment_filters": { "tags": [ "string" ], "tags_match": "string", "exclude_tags": [ "string" ], "is_subscribed": true, "custom_fields": {} }, "message_preview": "string", "rate_limit_per_minute": 1, "scheduled_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "recipient_count": 1, "pending_count": 1, "sent_count": 1, "delivered_count": 1, "read_count": 1, "failed_count": 1, "skipped_count": 1, "last_error": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Preview a broadcast audience `POST /broadcasts/audience-preview` Count (and sample) the contacts a segment reaches on an account. Access: `read` · MCP tool: `preview-broadcast-audience` ### Body - `profile_id` (string) - `account_id` (string; required) - `segment_filters` (object | null) - `segment_filters.tags` (array of string; ≤ 100 items) - `segment_filters.tags_match` (string; one of any, all) - `segment_filters.exclude_tags` (array of string; ≤ 100 items) - `segment_filters.is_subscribed` (boolean) - `segment_filters.custom_fields` (object) ```bash curl -X POST "https://api.socialit.com/v1/broadcasts/audience-preview" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "account_id": "string", "segment_filters": { "tags": [ "string" ], "tags_match": "any" } }' ``` Response 200: ```json { "object": "audience_preview", "count": 1, "sample": [ { "contact_id": "string", "name": "string", "platform_identifier": "string" } ] } ``` ## Get a broadcast `GET /broadcasts/{id}` Access: `read` · MCP tool: `get-broadcast` · Zernio: `GET /v1/broadcasts/{broadcastId}` ### Path parameters - `id` (string; required; 1–80 characters): broadcast id (brd_…) ```bash curl "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "broadcast", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "message": { "text": "string", "attachments": [ { "type": "string", "url": "https://example.com", "filename": "string" } ], "message_tag": "string" }, "segment_filters": { "tags": [ "string" ], "tags_match": "string", "exclude_tags": [ "string" ], "is_subscribed": true, "custom_fields": {} }, "message_preview": "string", "rate_limit_per_minute": 1, "scheduled_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "recipient_count": 1, "pending_count": 1, "sent_count": 1, "delivered_count": 1, "read_count": 1, "failed_count": 1, "skipped_count": 1, "last_error": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a broadcast `PATCH /broadcasts/{id}` Only while draft or scheduled (409 broadcast_not_editable). Access: `write` · MCP tool: `update-broadcast` · Zernio: `PATCH /v1/broadcasts/{broadcastId}` ### Path parameters - `id` (string; required; 1–80 characters): broadcast id (brd_…) ### Body - `name` (string; 1–200 characters) - `description` (string | null; ≤ 2000 characters) - `message` (object) - `message.text` (string | null; ≤ 4096 characters) - `message.attachments` (array of object; ≤ 10 items) - `message.attachments[].type` (string; one of image, video, audio, file) - `message.attachments[].url` (string; required; 1–2048 characters) - `message.attachments[].filename` (string; ≤ 255 characters) - `message.message_tag` (string | null; one of HUMAN_AGENT, CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE) - `segment_filters` (object | null) - `segment_filters.tags` (array of string; ≤ 100 items) - `segment_filters.tags_match` (string; one of any, all) - `segment_filters.exclude_tags` (array of string; ≤ 100 items) - `segment_filters.is_subscribed` (boolean) - `segment_filters.custom_fields` (object) - `rate_limit_per_minute` (integer | null; 1–6000) ```bash curl -X PATCH "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "description": "string", "message": { "text": "string", "attachments": [ { "type": "image", "url": "https://example.com" } ] }, "segment_filters": { "tags": [ "string" ], "tags_match": "any" }, "rate_limit_per_minute": 1 }' ``` Response 200: ```json { "object": "broadcast", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "message": { "text": "string", "attachments": [ { "type": "string", "url": "https://example.com", "filename": "string" } ], "message_tag": "string" }, "segment_filters": { "tags": [ "string" ], "tags_match": "string", "exclude_tags": [ "string" ], "is_subscribed": true, "custom_fields": {} }, "message_preview": "string", "rate_limit_per_minute": 1, "scheduled_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "recipient_count": 1, "pending_count": 1, "sent_count": 1, "delivered_count": 1, "read_count": 1, "failed_count": 1, "skipped_count": 1, "last_error": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a broadcast `DELETE /broadcasts/{id}` Not while sending (cancel first). Access: `write` · MCP tool: `delete-broadcast` · Zernio: `DELETE /v1/broadcasts/{broadcastId}` ### Path parameters - `id` (string; required; 1–80 characters): broadcast id (brd_…) ```bash curl -X DELETE "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "broadcast", "id": "string", "deleted": true } ``` ## Send a broadcast now `POST /broadcasts/{id}/send` Resolves the segment when no recipients were added (422 no_recipients when nothing matches) and starts sending in rate-limited batches. Access: `write` · MCP tool: `send-broadcast` · Zernio: `POST /v1/broadcasts/{broadcastId}/send` ### Path parameters - `id` (string; required; 1–80 characters): broadcast id (brd_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/send" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 200: ```json { "object": "broadcast", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "message": { "text": "string", "attachments": [ { "type": "string", "url": "https://example.com", "filename": "string" } ], "message_tag": "string" }, "segment_filters": { "tags": [ "string" ], "tags_match": "string", "exclude_tags": [ "string" ], "is_subscribed": true, "custom_fields": {} }, "message_preview": "string", "rate_limit_per_minute": 1, "scheduled_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "recipient_count": 1, "pending_count": 1, "sent_count": 1, "delivered_count": 1, "read_count": 1, "failed_count": 1, "skipped_count": 1, "last_error": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Schedule a broadcast `POST /broadcasts/{id}/schedule` Access: `write` · MCP tool: `schedule-broadcast` · Zernio: `POST /v1/broadcasts/{broadcastId}/schedule` ### Path parameters - `id` (string; required; 1–80 characters): broadcast id (brd_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `scheduled_at` (string (date-time); required) ```bash curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/schedule" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "scheduled_at": "2026-10-13T09:00:00.000Z" }' ``` Response 200: ```json { "object": "broadcast", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "message": { "text": "string", "attachments": [ { "type": "string", "url": "https://example.com", "filename": "string" } ], "message_tag": "string" }, "segment_filters": { "tags": [ "string" ], "tags_match": "string", "exclude_tags": [ "string" ], "is_subscribed": true, "custom_fields": {} }, "message_preview": "string", "rate_limit_per_minute": 1, "scheduled_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "recipient_count": 1, "pending_count": 1, "sent_count": 1, "delivered_count": 1, "read_count": 1, "failed_count": 1, "skipped_count": 1, "last_error": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Cancel a broadcast `POST /broadcasts/{id}/cancel` Pending recipients become skipped. Access: `write` · MCP tool: `cancel-broadcast` · Zernio: `POST /v1/broadcasts/{broadcastId}/cancel` ### Path parameters - `id` (string; required; 1–80 characters): broadcast id (brd_…) ```bash curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/cancel" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "broadcast", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "message": { "text": "string", "attachments": [ { "type": "string", "url": "https://example.com", "filename": "string" } ], "message_tag": "string" }, "segment_filters": { "tags": [ "string" ], "tags_match": "string", "exclude_tags": [ "string" ], "is_subscribed": true, "custom_fields": {} }, "message_preview": "string", "rate_limit_per_minute": 1, "scheduled_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "recipient_count": 1, "pending_count": 1, "sent_count": 1, "delivered_count": 1, "read_count": 1, "failed_count": 1, "skipped_count": 1, "last_error": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List broadcast recipients `GET /broadcasts/{id}/recipients` Access: `read` · MCP tool: `list-broadcast-recipients` · Zernio: `GET /v1/broadcasts/{broadcastId}/recipients` ### Path parameters - `id` (string; required; 1–80 characters): broadcast id (brd_…) ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, sent_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `status` (string) - `contact_id` (string) ```bash curl "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/recipients" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "broadcast_recipient", "id": "string", "broadcast_id": "string", "contact_id": "string", "channel_id": "string", "contact_name": "string", "platform_identifier": "string", "status": "pending", "message_id": "string", "error": "string", "error_code": "string", "sent_at": "2026-10-13T09:00:00.000Z", "delivered_at": "2026-10-13T09:00:00.000Z", "read_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Add broadcast recipients `POST /broadcasts/{id}/recipients` By contact_ids and/or use_segment. Contacts without a subscribed channel on the account are skipped. Access: `write` · MCP tool: `add-broadcast-recipients` · Zernio: `POST /v1/broadcasts/{broadcastId}/recipients` ### Path parameters - `id` (string; required; 1–80 characters): broadcast id (brd_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `contact_ids` (array of string; ≤ 10000 items) - `use_segment` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/recipients" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "contact_ids": [ "string" ], "use_segment": true }' ``` Response 200: ```json { "object": "broadcast_recipients_result", "added": 1, "skipped": 1, "recipient_count": 1 } ``` --- Source: https://socialit.com/docs/api-reference/broadcasts/ # Sequences API > Time-based drips: ordered steps (delay, message, optional condition) sent to enrolled contacts on one account; contacts exit on reply or unsubscribe. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List sequences `GET /sequences` Access: `read` · MCP tool: `list-sequences` · Zernio: `GET /v1/sequences` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string) - `account_id` (string) - `status` (string) - `platform` (string) ```bash curl "https://api.socialit.com/v1/sequences" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "sequence", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "steps": [ { "order": 1, "delay_minutes": 1, "message": { "text": null, "attachments": [], "message_tag": null }, "condition": { "variable": null, "operator": null, "value": null, "on_false": null } } ], "steps_count": 1, "message_preview": "string", "exit_on_reply": true, "exit_on_unsubscribe": true, "stats": { "total_enrolled": 1, "active": 1, "paused": 1, "completed": 1, "exited": 1 }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a sequence `POST /sequences` Access: `write` · MCP tool: `create-sequence` · Zernio: `POST /v1/sequences` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string) - `account_id` (string; required) - `platform` (string; one of instagram, facebook, x, bluesky, reddit, discord, mastodon, tiktok, twitter) - `name` (string; required; 1–200 characters) - `description` (string | null; ≤ 2000 characters) - `steps` (array of object; ≤ 50 items) - `steps[].order` (integer; required; 1–1000) - `steps[].delay_minutes` (integer; required; 0–525600) - `steps[].message` (object | null) - `steps[].message.text` (string | null; ≤ 4096 characters) - `steps[].message.attachments` (array of object; ≤ 10 items) - `steps[].message.attachments[].type` (string; one of image, video, audio, file) - `steps[].message.attachments[].url` (string; required; 1–2048 characters) - `steps[].message.attachments[].filename` (string; ≤ 255 characters) - `steps[].message.message_tag` (string | null; one of HUMAN_AGENT, CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE) - `steps[].condition` (object | null) - `steps[].condition.variable` (string; required; 1–200 characters) - `steps[].condition.operator` (string; required) - `steps[].condition.value` (any) - `steps[].condition.on_false` (string; one of skip, exit) - `exit_on_reply` (boolean) - `exit_on_unsubscribe` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/sequences" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "account_id": "string", "platform": "instagram", "name": "string", "description": "string" }' ``` Response 201: ```json { "object": "sequence", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "steps": [ { "order": 1, "delay_minutes": 1, "message": { "text": "string", "attachments": [ { "type": null, "url": null, "filename": null } ], "message_tag": "string" }, "condition": { "variable": "string", "operator": "string", "value": null, "on_false": "string" } } ], "steps_count": 1, "message_preview": "string", "exit_on_reply": true, "exit_on_unsubscribe": true, "stats": { "total_enrolled": 1, "active": 1, "paused": 1, "completed": 1, "exited": 1 }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get a sequence `GET /sequences/{id}` Access: `read` · MCP tool: `get-sequence` · Zernio: `GET /v1/sequences/{sequenceId}` ### Path parameters - `id` (string; required; 1–80 characters): sequence id (seq_…) ```bash curl "https://api.socialit.com/v1/sequences/seq_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "sequence", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "steps": [ { "order": 1, "delay_minutes": 1, "message": { "text": "string", "attachments": [ { "type": null, "url": null, "filename": null } ], "message_tag": "string" }, "condition": { "variable": "string", "operator": "string", "value": null, "on_false": "string" } } ], "steps_count": 1, "message_preview": "string", "exit_on_reply": true, "exit_on_unsubscribe": true, "stats": { "total_enrolled": 1, "active": 1, "paused": 1, "completed": 1, "exited": 1 }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a sequence `PATCH /sequences/{id}` steps can only be replaced while draft or paused (409 sequence_not_editable). Access: `write` · MCP tool: `update-sequence` · Zernio: `PATCH /v1/sequences/{sequenceId}` ### Path parameters - `id` (string; required; 1–80 characters): sequence id (seq_…) ### Body - `name` (string; 1–200 characters) - `description` (string | null; ≤ 2000 characters) - `steps` (array of object; ≤ 50 items) - `steps[].order` (integer; required; 1–1000) - `steps[].delay_minutes` (integer; required; 0–525600) - `steps[].message` (object | null) - `steps[].message.text` (string | null; ≤ 4096 characters) - `steps[].message.attachments` (array of object; ≤ 10 items) - `steps[].message.attachments[].type` (string; one of image, video, audio, file) - `steps[].message.attachments[].url` (string; required; 1–2048 characters) - `steps[].message.attachments[].filename` (string; ≤ 255 characters) - `steps[].message.message_tag` (string | null; one of HUMAN_AGENT, CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE) - `steps[].condition` (object | null) - `steps[].condition.variable` (string; required; 1–200 characters) - `steps[].condition.operator` (string; required) - `steps[].condition.value` (any) - `steps[].condition.on_false` (string; one of skip, exit) - `exit_on_reply` (boolean) - `exit_on_unsubscribe` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/sequences/seq_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "description": "string", "steps": [ { "order": 1, "delay_minutes": 0 } ], "exit_on_reply": true, "exit_on_unsubscribe": true }' ``` Response 200: ```json { "object": "sequence", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "steps": [ { "order": 1, "delay_minutes": 1, "message": { "text": "string", "attachments": [ { "type": null, "url": null, "filename": null } ], "message_tag": "string" }, "condition": { "variable": "string", "operator": "string", "value": null, "on_false": "string" } } ], "steps_count": 1, "message_preview": "string", "exit_on_reply": true, "exit_on_unsubscribe": true, "stats": { "total_enrolled": 1, "active": 1, "paused": 1, "completed": 1, "exited": 1 }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a sequence `DELETE /sequences/{id}` Live enrollments exit with sequence_deleted. Access: `write` · MCP tool: `delete-sequence` · Zernio: `DELETE /v1/sequences/{sequenceId}` ### Path parameters - `id` (string; required; 1–80 characters): sequence id (seq_…) ```bash curl -X DELETE "https://api.socialit.com/v1/sequences/seq_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "sequence", "id": "string", "deleted": true } ``` ## Activate a sequence `POST /sequences/{id}/activate` Paused enrollments resume (overdue steps are sent now). Access: `write` · MCP tool: `activate-sequence` · Zernio: `POST /v1/sequences/{sequenceId}/activate` ### Path parameters - `id` (string; required; 1–80 characters): sequence id (seq_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/sequences/seq_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/activate" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 200: ```json { "object": "sequence", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "steps": [ { "order": 1, "delay_minutes": 1, "message": { "text": "string", "attachments": [ { "type": null, "url": null, "filename": null } ], "message_tag": "string" }, "condition": { "variable": "string", "operator": "string", "value": null, "on_false": "string" } } ], "steps_count": 1, "message_preview": "string", "exit_on_reply": true, "exit_on_unsubscribe": true, "stats": { "total_enrolled": 1, "active": 1, "paused": 1, "completed": 1, "exited": 1 }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Pause a sequence `POST /sequences/{id}/pause` Access: `write` · MCP tool: `pause-sequence` · Zernio: `POST /v1/sequences/{sequenceId}/pause` ### Path parameters - `id` (string; required; 1–80 characters): sequence id (seq_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/sequences/seq_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pause" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 200: ```json { "object": "sequence", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "steps": [ { "order": 1, "delay_minutes": 1, "message": { "text": "string", "attachments": [ { "type": null, "url": null, "filename": null } ], "message_tag": "string" }, "condition": { "variable": "string", "operator": "string", "value": null, "on_false": "string" } } ], "steps_count": 1, "message_preview": "string", "exit_on_reply": true, "exit_on_unsubscribe": true, "stats": { "total_enrolled": 1, "active": 1, "paused": 1, "completed": 1, "exited": 1 }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Enroll contacts in a sequence `POST /sequences/{id}/enroll` The channel is the contact's subscribed channel on the sequence account unless channel_ids pin one. Already-enrolled contacts are skipped. Access: `write` · MCP tool: `enroll-sequence-contacts` · Zernio: `POST /v1/sequences/{sequenceId}/enroll` ### Path parameters - `id` (string; required; 1–80 characters): sequence id (seq_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `contact_ids` (array of string; required; 1–1000 items) - `channel_ids` (array of string; ≤ 1000 items) ```bash curl -X POST "https://api.socialit.com/v1/sequences/seq_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/enroll" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "contact_ids": [ "string" ], "channel_ids": [ "string" ] }' ``` Response 200: ```json { "object": "sequence_enroll_result", "enrolled": 1, "skipped": 1, "failed": 1, "results": [ { "contact_id": "string", "success": true, "enrollment_id": "string", "error": "string" } ] } ``` ## Unenroll a contact `DELETE /sequences/{id}/enroll/{contactId}` Access: `write` · MCP tool: `unenroll-sequence-contact` · Zernio: `DELETE /v1/sequences/{sequenceId}/enroll/{contactId}` ### Path parameters - `id` (string; required; 1–80 characters): sequence id (seq_…) - `contactId` (string; required; 1–80 characters): contact id (con_…) ```bash curl -X DELETE "https://api.socialit.com/v1/sequences/seq_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/enroll/con_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "sequence_enrollment", "id": "string", "sequence_id": "string", "contact_id": "string", "channel_id": "string", "contact_name": "string", "platform_identifier": "string", "status": "active", "exit_reason": "string", "current_step_index": 1, "steps_sent": 1, "next_step_at": "2026-10-13T09:00:00.000Z", "last_step_sent_at": "2026-10-13T09:00:00.000Z", "last_error": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List sequence enrollments `GET /sequences/{id}/enrollments` Access: `read` · MCP tool: `list-sequence-enrollments` · Zernio: `GET /v1/sequences/{sequenceId}/enrollments` ### Path parameters - `id` (string; required; 1–80 characters): sequence id (seq_…) ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, next_step_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `status` (string) - `contact_id` (string) ```bash curl "https://api.socialit.com/v1/sequences/seq_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/enrollments" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "sequence_enrollment", "id": "string", "sequence_id": "string", "contact_id": "string", "channel_id": "string", "contact_name": "string", "platform_identifier": "string", "status": "active", "exit_reason": "string", "current_step_index": 1, "steps_sent": 1, "next_step_at": "2026-10-13T09:00:00.000Z", "last_step_sent_at": "2026-10-13T09:00:00.000Z", "last_error": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` --- Source: https://socialit.com/docs/api-reference/sequences/ # Workflows API > Event-driven automation graphs: a trigger (message, keyword, comment, referral, reaction, contact change, API call, schedule) and nodes (send message, reply / private reply, wait, condition, HTTP request, AI reply with Claude, tags, fields, sequences, assignment). Every graph change records a version; runs are durable and have a timeline. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List workflows `GET /workflows` Access: `read` · MCP tool: `list-workflows` · Zernio: `GET /v1/workflows` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, updated_at, name) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string) - `account_id` (string) - `status` (string) - `platform` (string) - `trigger_type` (string) ```bash curl "https://api.socialit.com/v1/workflows" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "workflow", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "trigger_type": "string", "entry_node_id": "string", "nodes": [ { "id": "string", "type": "string", "label": "string", "position": { "x": null, "y": null }, "config": {} } ], "edges": [ { "id": "string", "source": "string", "target": "string", "source_handle": "string" } ], "node_count": 1, "version": 1, "stats": { "total_started": 1, "total_completed": 1, "total_exited": 1, "total_failed": 1, "running": 1 }, "activated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a workflow `POST /workflows` Validates the graph structure (unique ids, known node types, edges between real nodes, valid handles). Created as draft. Access: `write` · MCP tool: `create-workflow` · Zernio: `POST /v1/workflows` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string) - `account_id` (string | null) - `platform` (string; one of instagram, facebook, x, bluesky, reddit, discord, mastodon, tiktok, twitter) - `name` (string; required; 1–200 characters) - `description` (string | null; ≤ 2000 characters) - `nodes` (array of object; ≤ 200 items) - `nodes[].id` (string; required; 1–64 characters) - `nodes[].type` (string; required; one of trigger, send_message, reply_to_comment, private_reply, wait_for_reply, condition, set_variable, delay, http_request, ai, assign_conversation, handoff, …) - `nodes[].label` (string | null; ≤ 80 characters) - `nodes[].position` (object | null) - `nodes[].position.x` (number) - `nodes[].position.y` (number) - `nodes[].config` (object) - `edges` (array of object; ≤ 400 items) - `edges[].id` (string; required; 1–64 characters) - `edges[].source` (string; required; 1–64 characters) - `edges[].target` (string; required; 1–64 characters) - `edges[].source_handle` (string | null; ≤ 64 characters) - `edges[].sourceHandle` (string | null; ≤ 64 characters) - `entry_node_id` (string | null; ≤ 64 characters) ```bash curl -X POST "https://api.socialit.com/v1/workflows" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "account_id": "string", "platform": "instagram", "name": "string", "description": "string" }' ``` Response 201: ```json { "object": "workflow", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "trigger_type": "string", "entry_node_id": "string", "nodes": [ { "id": "string", "type": "string", "label": "string", "position": { "x": 1.5, "y": 1.5 }, "config": {} } ], "edges": [ { "id": "string", "source": "string", "target": "string", "source_handle": "string" } ], "node_count": 1, "version": 1, "stats": { "total_started": 1, "total_completed": 1, "total_exited": 1, "total_failed": 1, "running": 1 }, "activated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List workflow node types `GET /workflows/node-types` Catalog of node types with their output handles and config JSON schema (drives the builder). Access: `read` · MCP tool: `list-workflow-node-types` ### Query parameters - `page` (integer; ≥ 1) - `limit` (integer; 1–100) ```bash curl "https://api.socialit.com/v1/workflows/node-types" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "workflow_node_type", "type": "string", "group": "string", "label": "string", "description": "string", "handles": [ "string" ], "config_schema": {}, "platforms": [ "string" ], "alias_of": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a workflow `GET /workflows/{id}` Access: `read` · MCP tool: `get-workflow` · Zernio: `GET /v1/workflows/{workflowId}` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) ```bash curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "workflow", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "trigger_type": "string", "entry_node_id": "string", "nodes": [ { "id": "string", "type": "string", "label": "string", "position": { "x": 1.5, "y": 1.5 }, "config": {} } ], "edges": [ { "id": "string", "source": "string", "target": "string", "source_handle": "string" } ], "node_count": 1, "version": 1, "stats": { "total_started": 1, "total_completed": 1, "total_exited": 1, "total_failed": 1, "running": 1 }, "activated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a workflow `PATCH /workflows/{id}` The graph (nodes, edges, entry_node_id, replaced wholesale) is editable only while draft or paused (409 workflow_not_editable); name, description and account any time. Graph, name and description changes record a version. Access: `write` · MCP tool: `update-workflow` · Zernio: `PATCH /v1/workflows/{workflowId}` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) ### Body - `name` (string; 1–200 characters) - `description` (string | null; ≤ 2000 characters) - `account_id` (string | null) - `nodes` (array of object; ≤ 200 items) - `nodes[].id` (string; required; 1–64 characters) - `nodes[].type` (string; required; one of trigger, send_message, reply_to_comment, private_reply, wait_for_reply, condition, set_variable, delay, http_request, ai, assign_conversation, handoff, …) - `nodes[].label` (string | null; ≤ 80 characters) - `nodes[].position` (object | null) - `nodes[].position.x` (number) - `nodes[].position.y` (number) - `nodes[].config` (object) - `edges` (array of object; ≤ 400 items) - `edges[].id` (string; required; 1–64 characters) - `edges[].source` (string; required; 1–64 characters) - `edges[].target` (string; required; 1–64 characters) - `edges[].source_handle` (string | null; ≤ 64 characters) - `edges[].sourceHandle` (string | null; ≤ 64 characters) - `entry_node_id` (string | null; ≤ 64 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "description": "string", "account_id": "string", "nodes": [ { "id": "string", "type": "trigger" } ], "edges": [ { "id": "string", "source": "string", "target": "string" } ] }' ``` Response 200: ```json { "object": "workflow", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "trigger_type": "string", "entry_node_id": "string", "nodes": [ { "id": "string", "type": "string", "label": "string", "position": { "x": 1.5, "y": 1.5 }, "config": {} } ], "edges": [ { "id": "string", "source": "string", "target": "string", "source_handle": "string" } ], "node_count": 1, "version": 1, "stats": { "total_started": 1, "total_completed": 1, "total_exited": 1, "total_failed": 1, "running": 1 }, "activated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a workflow `DELETE /workflows/{id}` Access: `write` · MCP tool: `delete-workflow` · Zernio: `DELETE /v1/workflows/{workflowId}` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) ```bash curl -X DELETE "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "workflow", "id": "string", "deleted": true } ``` ## Activate a workflow `POST /workflows/{id}/activate` Requires a complete graph: one trigger, every node reachable and valid, an account when the graph messages (422 workflow_invalid with errors). Access: `write` · MCP tool: `activate-workflow` · Zernio: `POST /v1/workflows/{workflowId}/activate` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/activate" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 200: ```json { "object": "workflow", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "trigger_type": "string", "entry_node_id": "string", "nodes": [ { "id": "string", "type": "string", "label": "string", "position": { "x": 1.5, "y": 1.5 }, "config": {} } ], "edges": [ { "id": "string", "source": "string", "target": "string", "source_handle": "string" } ], "node_count": 1, "version": 1, "stats": { "total_started": 1, "total_completed": 1, "total_exited": 1, "total_failed": 1, "running": 1 }, "activated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Pause a workflow `POST /workflows/{id}/pause` Stops new runs; in-flight runs finish. Access: `write` · MCP tool: `pause-workflow` · Zernio: `POST /v1/workflows/{workflowId}/pause` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pause" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 200: ```json { "object": "workflow", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "trigger_type": "string", "entry_node_id": "string", "nodes": [ { "id": "string", "type": "string", "label": "string", "position": { "x": 1.5, "y": 1.5 }, "config": {} } ], "edges": [ { "id": "string", "source": "string", "target": "string", "source_handle": "string" } ], "node_count": 1, "version": 1, "stats": { "total_started": 1, "total_completed": 1, "total_exited": 1, "total_failed": 1, "running": 1 }, "activated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Duplicate a workflow `POST /workflows/{id}/duplicate` Access: `write` · MCP tool: `duplicate-workflow` · Zernio: `POST /v1/workflows/{workflowId}/duplicate` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/duplicate" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 201: ```json { "object": "workflow", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "trigger_type": "string", "entry_node_id": "string", "nodes": [ { "id": "string", "type": "string", "label": "string", "position": { "x": 1.5, "y": 1.5 }, "config": {} } ], "edges": [ { "id": "string", "source": "string", "target": "string", "source_handle": "string" } ], "node_count": 1, "version": 1, "stats": { "total_started": 1, "total_completed": 1, "total_exited": 1, "total_failed": 1, "running": 1 }, "activated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List workflow versions `GET /workflows/{id}/versions` Access: `read` · MCP tool: `list-workflow-versions` · Zernio: `GET /v1/workflows/{workflowId}/versions` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR ```bash curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/versions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "workflow_version", "id": "string", "workflow_id": "string", "version": 1, "name": "string", "description": "string", "entry_node_id": "string", "nodes": [ { "id": "string", "type": "string", "label": "string", "position": { "x": null, "y": null }, "config": {} } ], "edges": [ { "id": "string", "source": "string", "target": "string", "source_handle": "string" } ], "account_id": "string", "platform": "string", "created_by": { "type": "string", "id": "string", "name": "string" }, "restored_from_version": 1, "created_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a workflow version `GET /workflows/{id}/versions/{version}` Access: `read` · MCP tool: `get-workflow-version` · Zernio: `GET /v1/workflows/{workflowId}/versions/{version}` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) - `version` (integer; required; ≥ 1) ```bash curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/versions/VERSION" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "workflow_version", "id": "string", "workflow_id": "string", "version": 1, "name": "string", "description": "string", "entry_node_id": "string", "nodes": [ { "id": "string", "type": "string", "label": "string", "position": { "x": 1.5, "y": 1.5 }, "config": {} } ], "edges": [ { "id": "string", "source": "string", "target": "string", "source_handle": "string" } ], "account_id": "string", "platform": "string", "created_by": { "type": "string", "id": "string", "name": "string" }, "restored_from_version": 1, "created_at": "2026-10-13T09:00:00.000Z" } ``` ## Restore a workflow version `POST /workflows/{id}/versions/{version}/restore` Copies the version graph back as a new version (restored_from_version). Only while draft or paused. Access: `write` · MCP tool: `restore-workflow-version` · Zernio: `POST /v1/workflows/{workflowId}/versions/{version}/restore` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) - `version` (integer; required; ≥ 1) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/versions/VERSION/restore" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 200: ```json { "object": "workflow", "id": "string", "profile_id": "string", "account_id": "string", "account_name": "string", "platform": "string", "name": "string", "description": "string", "status": "draft", "trigger_type": "string", "entry_node_id": "string", "nodes": [ { "id": "string", "type": "string", "label": "string", "position": { "x": 1.5, "y": 1.5 }, "config": {} } ], "edges": [ { "id": "string", "source": "string", "target": "string", "source_handle": "string" } ], "node_count": 1, "version": 1, "stats": { "total_started": 1, "total_completed": 1, "total_exited": 1, "total_failed": 1, "running": 1 }, "activated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List workflow runs `GET /workflows/{id}/executions` Access: `read` · MCP tool: `list-workflow-executions` · Zernio: `GET /v1/workflows/{workflowId}/executions` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, updated_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `status` (string) - `contact_id` (string) ```bash curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/executions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "workflow_execution", "id": "string", "workflow_id": "string", "workflow_version": 1, "status": "running", "trigger": { "type": "string", "text": "string" }, "contact_id": "string", "conversation_id": "string", "platform_identifier": "string", "current_node_id": "string", "waiting_for": { "kind": "string", "node_id": "string", "until": "string" }, "variables": {}, "step_count": 1, "last_error": "string", "resume_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Start a workflow run manually `POST /workflows/{id}/executions` Test run for any status, on a contact_id, conversation_id or to (phone), with text seeding last_message. Access: `write` · MCP tool: `start-workflow-execution` · Zernio: `POST /v1/workflows/{workflowId}/executions` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `contact_id` (string) - `conversation_id` (string) - `to` (string; ≤ 32 characters) - `text` (string; ≤ 4096 characters) - `variables` (object) ```bash curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/executions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "contact_id": "string", "conversation_id": "string", "to": "+15551234567", "text": "string", "variables": {} }' ``` Response 201: ```json { "object": "workflow_execution", "id": "string", "workflow_id": "string", "workflow_version": 1, "status": "running", "trigger": { "type": "string", "text": "string" }, "contact_id": "string", "conversation_id": "string", "platform_identifier": "string", "current_node_id": "string", "waiting_for": { "kind": "string", "node_id": "string", "until": "string" }, "variables": {}, "step_count": 1, "last_error": "string", "resume_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Trigger an API workflow `POST /workflows/{id}/trigger` For active workflows with an api_call trigger: one of contact_id, conversation_id or to, plus variables. Access: `write` · MCP tool: `trigger-workflow` · Zernio: `POST /v1/workflows/{workflowId}/trigger` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `contact_id` (string) - `conversation_id` (string) - `to` (string; ≤ 32 characters) - `variables` (object) ```bash curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/trigger" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "contact_id": "string", "conversation_id": "string", "to": "+15551234567", "variables": {} }' ``` Response 201: ```json { "object": "workflow_execution", "id": "string", "workflow_id": "string", "workflow_version": 1, "status": "running", "trigger": { "type": "string", "text": "string" }, "contact_id": "string", "conversation_id": "string", "platform_identifier": "string", "current_node_id": "string", "waiting_for": { "kind": "string", "node_id": "string", "until": "string" }, "variables": {}, "step_count": 1, "last_error": "string", "resume_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get a workflow run `GET /workflows/{id}/executions/{executionId}` Access: `read` · MCP tool: `get-workflow-execution` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) - `executionId` (string; required; 1–80 characters): workflowExecution id (wfx_…) ```bash curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/executions/wfx_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "workflow_execution", "id": "string", "workflow_id": "string", "workflow_version": 1, "status": "running", "trigger": { "type": "string", "text": "string" }, "contact_id": "string", "conversation_id": "string", "platform_identifier": "string", "current_node_id": "string", "waiting_for": { "kind": "string", "node_id": "string", "until": "string" }, "variables": {}, "step_count": 1, "last_error": "string", "resume_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Stop a workflow run `POST /workflows/{id}/executions/{executionId}/cancel` Access: `write` · MCP tool: `cancel-workflow-execution` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) - `executionId` (string; required; 1–80 characters): workflowExecution id (wfx_…) ```bash curl -X POST "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/executions/wfx_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/cancel" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "workflow_execution", "id": "string", "workflow_id": "string", "workflow_version": 1, "status": "running", "trigger": { "type": "string", "text": "string" }, "contact_id": "string", "conversation_id": "string", "platform_identifier": "string", "current_node_id": "string", "waiting_for": { "kind": "string", "node_id": "string", "until": "string" }, "variables": {}, "step_count": 1, "last_error": "string", "resume_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "completed_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get a run timeline `GET /workflows/{id}/executions/{executionId}/events` Access: `read` · MCP tool: `list-workflow-execution-events` · Zernio: `GET /v1/workflows/{workflowId}/executions/{executionId}/events` ### Path parameters - `id` (string; required; 1–80 characters): workflow id (wf_…) - `executionId` (string; required; 1–80 characters): workflowExecution id (wfx_…) ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR ```bash curl "https://api.socialit.com/v1/workflows/wf_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/executions/wfx_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/events" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "workflow_execution_event", "id": "string", "execution_id": "string", "action": "string", "status": "string", "node_id": "string", "node_type": "string", "source_handle": "string", "duration_ms": 1, "error_message": "string", "meta": {}, "at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` --- Source: https://socialit.com/docs/api-reference/workflows/ # Comment Automations API > Comment-to-DM (ManyChat-style): keyword rules per account or post answer comments with a private DM (Instagram, Facebook) and / or a public reply (also TikTok, Threads, LinkedIn, YouTube, Bluesky, Reddit), with audience filters, follow gates, repeat policies and tracked links. Each comment is answered at most once. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List comment automations `GET /comment-automations` Access: `read` · MCP tool: `list-comment-automations` · Zernio: `GET /v1/comment-automations` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `profile_id` (string) - `account_id` (string) - `platform` (string) - `trigger` (string) - `is_active` (string) ```bash curl "https://api.socialit.com/v1/comment-automations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "comment_automation", "id": "string", "profile_id": "string", "account_id": "string", "platform": "string", "name": "string", "trigger": "string", "platform_post_id": "string", "post_id": "string", "post_title": "string", "keywords": [ "string" ], "match_mode": "string", "exclude_keywords": [ "string" ], "typo_tolerance": true, "dm_message": "string", "dm_message_variations": [ "string" ], "buttons": [ { "type": "string", "title": "string", "url": "https://example.com", "payload": "string", "phone": "+15551234567" } ], "template": {}, "quick_replies": [ { "title": "string", "payload": "string", "image_url": "https://example.com" } ], "dm_media": { "type": "string", "url": "https://example.com" }, "comment_reply": "string", "comment_reply_variations": [ "string" ], "public_reply_policy": "string", "dm_delay_seconds": 1, "comment_reply_delay_seconds": 1, "link_tracking": true, "click_tag": "string", "also_match_in_dms": true, "audience": { "follower_status": "string", "min_follower_count": 1, "when_unknown": "string", "tap_to_unlock": true }, "follow_gate": { "message": "string", "button_label": "string", "not_following_message": "string" } } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a comment automation `POST /comment-automations` Access: `write` · MCP tool: `create-comment-automation` · Zernio: `POST /v1/comment-automations` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string) - `account_id` (string; required) - `name` (string; required; 1–200 characters) - `trigger` (string; one of comment, live_comment, story_reply, story_mention) - `platform_post_id` (string | null; ≤ 255 characters) - `post_id` (string | null) - `post_title` (string | null; ≤ 300 characters) - `keywords` (array of string; ≤ 50 items) - `match_mode` (string; one of contains, word, exact) - `exclude_keywords` (array of string; ≤ 50 items) - `typo_tolerance` (boolean) - `dm_message` (string | null; ≤ 1000 characters) - `dm_message_variations` (array of string; ≤ 5 items) - `buttons` (array of object | null; ≤ 3 items) - `buttons[].type` (string; required; one of url, postback, phone) - `buttons[].title` (string; required; 1–20 characters) - `buttons[].url` (string; ≤ 2048 characters) - `buttons[].payload` (string; ≤ 1000 characters) - `buttons[].phone` (string; ≤ 32 characters) - `template` (object | null) - `template.type` (string; required; one of generic) - `template.image_aspect_ratio` (string; one of horizontal, square) - `template.elements` (array of object; required; 1–10 items) - `template.elements[].title` (string; required; 1–80 characters) - `template.elements[].subtitle` (string; ≤ 80 characters) - `template.elements[].image_url` (string; ≤ 2048 characters) - `template.elements[].buttons` (array of object; ≤ 3 items) - `template.elements[].buttons[].type` (string; required; one of url, postback, phone) - `template.elements[].buttons[].title` (string; required; 1–20 characters) - `template.elements[].buttons[].url` (string; ≤ 2048 characters) - `template.elements[].buttons[].payload` (string; ≤ 1000 characters) - `template.elements[].buttons[].phone` (string; ≤ 32 characters) - `quick_replies` (array of object | null; ≤ 13 items) - `quick_replies[].title` (string; required; 1–20 characters) - `quick_replies[].payload` (string; required; ≤ 1000 characters) - `quick_replies[].image_url` (string; ≤ 2048 characters) - `dm_media` (object | null) - `dm_media.type` (string; required; one of image, video, audio, file) - `dm_media.url` (string; required; ≤ 2048 characters) - `comment_reply` (string | null; ≤ 2000 characters) - `comment_reply_variations` (array of string; ≤ 5 items) - `public_reply_policy` (string; one of after_dm, always) - `dm_delay_seconds` (integer; 0–86400) - `comment_reply_delay_seconds` (integer; 0–86400) - `link_tracking` (boolean) - `click_tag` (string | null; ≤ 64 characters) - `also_match_in_dms` (boolean) - `audience` (object | null) - `audience.follower_status` (string; one of any, follower, non_follower) - `audience.min_follower_count` (integer) - `audience.when_unknown` (string; one of send, skip, verify) - `audience.tap_to_unlock` (boolean) - `follow_gate` (object | null) - `follow_gate.message` (string; ≤ 640 characters) - `follow_gate.button_label` (string; ≤ 20 characters) - `follow_gate.not_following_message` (string; ≤ 1000 characters) - `repeat_policy` (object) - `repeat_policy.mode` (string; required; one of once, every_comment) - `repeat_policy.cooldown_hours` (integer | null; 1–8760) - `dedupe_same_text_hours` (integer | null; 1–8760) - `actions` (object) - `actions.like_comment` (boolean) - `actions.hide_comment` (boolean) - `is_active` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/comment-automations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "account_id": "string", "name": "string", "trigger": "comment", "platform_post_id": "string" }' ``` Response 201: ```json { "object": "comment_automation", "id": "string", "profile_id": "string", "account_id": "string", "platform": "string", "name": "string", "trigger": "string", "platform_post_id": "string", "post_id": "string", "post_title": "string", "keywords": [ "string" ], "match_mode": "string", "exclude_keywords": [ "string" ], "typo_tolerance": true, "dm_message": "string", "dm_message_variations": [ "string" ], "buttons": [ { "type": "string", "title": "string", "url": "https://example.com", "payload": "string", "phone": "+15551234567" } ], "template": {}, "quick_replies": [ { "title": "string", "payload": "string", "image_url": "https://example.com" } ], "dm_media": { "type": "string", "url": "https://example.com" }, "comment_reply": "string", "comment_reply_variations": [ "string" ], "public_reply_policy": "string", "dm_delay_seconds": 1, "comment_reply_delay_seconds": 1, "link_tracking": true, "click_tag": "string", "also_match_in_dms": true, "audience": { "follower_status": "string", "min_follower_count": 1, "when_unknown": "string", "tap_to_unlock": true }, "follow_gate": { "message": "string", "button_label": "string", "not_following_message": "string" }, "repeat_policy": { "mode": "string", "cooldown_hours": 1 }, "dedupe_same_text_hours": 1, "actions": { "like_comment": true, "hide_comment": true }, "is_active": true, "stats": { "triggered": 1, "dms_sent": 1, "dms_failed": 1, "unique_contacts": 1, "public_replies_sent": 1, "tracked_sends": 1, "link_clicks": 1, "unique_clicks": 1, "delivered": 1, "read": 1, "audience_skipped": 1, "follow_gate_sent": 1, "follow_gate_passed": 1, "follow_gate_failed": 1 }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get a comment automation `GET /comment-automations/{id}` Access: `read` · MCP tool: `get-comment-automation` · Zernio: `GET /v1/comment-automations/{automationId}` ### Path parameters - `id` (string; required; 1–80 characters): commentAutomation id (cau_…) ```bash curl "https://api.socialit.com/v1/comment-automations/cau_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "comment_automation", "id": "string", "profile_id": "string", "account_id": "string", "platform": "string", "name": "string", "trigger": "string", "platform_post_id": "string", "post_id": "string", "post_title": "string", "keywords": [ "string" ], "match_mode": "string", "exclude_keywords": [ "string" ], "typo_tolerance": true, "dm_message": "string", "dm_message_variations": [ "string" ], "buttons": [ { "type": "string", "title": "string", "url": "https://example.com", "payload": "string", "phone": "+15551234567" } ], "template": {}, "quick_replies": [ { "title": "string", "payload": "string", "image_url": "https://example.com" } ], "dm_media": { "type": "string", "url": "https://example.com" }, "comment_reply": "string", "comment_reply_variations": [ "string" ], "public_reply_policy": "string", "dm_delay_seconds": 1, "comment_reply_delay_seconds": 1, "link_tracking": true, "click_tag": "string", "also_match_in_dms": true, "audience": { "follower_status": "string", "min_follower_count": 1, "when_unknown": "string", "tap_to_unlock": true }, "follow_gate": { "message": "string", "button_label": "string", "not_following_message": "string" }, "repeat_policy": { "mode": "string", "cooldown_hours": 1 }, "dedupe_same_text_hours": 1, "actions": { "like_comment": true, "hide_comment": true }, "is_active": true, "stats": { "triggered": 1, "dms_sent": 1, "dms_failed": 1, "unique_contacts": 1, "public_replies_sent": 1, "tracked_sends": 1, "link_clicks": 1, "unique_clicks": 1, "delivered": 1, "read": 1, "audience_skipped": 1, "follow_gate_sent": 1, "follow_gate_passed": 1, "follow_gate_failed": 1 }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update a comment automation `PATCH /comment-automations/{id}` Access: `write` · MCP tool: `update-comment-automation` · Zernio: `PATCH /v1/comment-automations/{automationId}` ### Path parameters - `id` (string; required; 1–80 characters): commentAutomation id (cau_…) ### Body - `name` (string; 1–200 characters) - `trigger` (string; one of comment, live_comment, story_reply, story_mention) - `platform_post_id` (string | null; ≤ 255 characters) - `post_id` (string | null) - `post_title` (string | null; ≤ 300 characters) - `keywords` (array of string; ≤ 50 items) - `match_mode` (string; one of contains, word, exact) - `exclude_keywords` (array of string; ≤ 50 items) - `typo_tolerance` (boolean) - `dm_message` (string | null; ≤ 1000 characters) - `dm_message_variations` (array of string; ≤ 5 items) - `buttons` (array of object | null; ≤ 3 items) - `buttons[].type` (string; required; one of url, postback, phone) - `buttons[].title` (string; required; 1–20 characters) - `buttons[].url` (string; ≤ 2048 characters) - `buttons[].payload` (string; ≤ 1000 characters) - `buttons[].phone` (string; ≤ 32 characters) - `template` (object | null) - `template.type` (string; required; one of generic) - `template.image_aspect_ratio` (string; one of horizontal, square) - `template.elements` (array of object; required; 1–10 items) - `template.elements[].title` (string; required; 1–80 characters) - `template.elements[].subtitle` (string; ≤ 80 characters) - `template.elements[].image_url` (string; ≤ 2048 characters) - `template.elements[].buttons` (array of object; ≤ 3 items) - `template.elements[].buttons[].type` (string; required; one of url, postback, phone) - `template.elements[].buttons[].title` (string; required; 1–20 characters) - `template.elements[].buttons[].url` (string; ≤ 2048 characters) - `template.elements[].buttons[].payload` (string; ≤ 1000 characters) - `template.elements[].buttons[].phone` (string; ≤ 32 characters) - `quick_replies` (array of object | null; ≤ 13 items) - `quick_replies[].title` (string; required; 1–20 characters) - `quick_replies[].payload` (string; required; ≤ 1000 characters) - `quick_replies[].image_url` (string; ≤ 2048 characters) - `dm_media` (object | null) - `dm_media.type` (string; required; one of image, video, audio, file) - `dm_media.url` (string; required; ≤ 2048 characters) - `comment_reply` (string | null; ≤ 2000 characters) - `comment_reply_variations` (array of string; ≤ 5 items) - `public_reply_policy` (string; one of after_dm, always) - `dm_delay_seconds` (integer; 0–86400) - `comment_reply_delay_seconds` (integer; 0–86400) - `link_tracking` (boolean) - `click_tag` (string | null; ≤ 64 characters) - `also_match_in_dms` (boolean) - `audience` (object | null) - `audience.follower_status` (string; one of any, follower, non_follower) - `audience.min_follower_count` (integer) - `audience.when_unknown` (string; one of send, skip, verify) - `audience.tap_to_unlock` (boolean) - `follow_gate` (object | null) - `follow_gate.message` (string; ≤ 640 characters) - `follow_gate.button_label` (string; ≤ 20 characters) - `follow_gate.not_following_message` (string; ≤ 1000 characters) - `repeat_policy` (object) - `repeat_policy.mode` (string; required; one of once, every_comment) - `repeat_policy.cooldown_hours` (integer | null; 1–8760) - `dedupe_same_text_hours` (integer | null; 1–8760) - `actions` (object) - `actions.like_comment` (boolean) - `actions.hide_comment` (boolean) - `is_active` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/comment-automations/cau_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "trigger": "comment", "platform_post_id": "string", "post_id": "string", "post_title": "string" }' ``` Response 200: ```json { "object": "comment_automation", "id": "string", "profile_id": "string", "account_id": "string", "platform": "string", "name": "string", "trigger": "string", "platform_post_id": "string", "post_id": "string", "post_title": "string", "keywords": [ "string" ], "match_mode": "string", "exclude_keywords": [ "string" ], "typo_tolerance": true, "dm_message": "string", "dm_message_variations": [ "string" ], "buttons": [ { "type": "string", "title": "string", "url": "https://example.com", "payload": "string", "phone": "+15551234567" } ], "template": {}, "quick_replies": [ { "title": "string", "payload": "string", "image_url": "https://example.com" } ], "dm_media": { "type": "string", "url": "https://example.com" }, "comment_reply": "string", "comment_reply_variations": [ "string" ], "public_reply_policy": "string", "dm_delay_seconds": 1, "comment_reply_delay_seconds": 1, "link_tracking": true, "click_tag": "string", "also_match_in_dms": true, "audience": { "follower_status": "string", "min_follower_count": 1, "when_unknown": "string", "tap_to_unlock": true }, "follow_gate": { "message": "string", "button_label": "string", "not_following_message": "string" }, "repeat_policy": { "mode": "string", "cooldown_hours": 1 }, "dedupe_same_text_hours": 1, "actions": { "like_comment": true, "hide_comment": true }, "is_active": true, "stats": { "triggered": 1, "dms_sent": 1, "dms_failed": 1, "unique_contacts": 1, "public_replies_sent": 1, "tracked_sends": 1, "link_clicks": 1, "unique_clicks": 1, "delivered": 1, "read": 1, "audience_skipped": 1, "follow_gate_sent": 1, "follow_gate_passed": 1, "follow_gate_failed": 1 }, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a comment automation `DELETE /comment-automations/{id}` Access: `write` · MCP tool: `delete-comment-automation` · Zernio: `DELETE /v1/comment-automations/{automationId}` ### Path parameters - `id` (string; required; 1–80 characters): commentAutomation id (cau_…) ```bash curl -X DELETE "https://api.socialit.com/v1/comment-automations/cau_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "comment_automation", "id": "string", "deleted": true } ``` ## List comment automation logs `GET /comment-automations/{id}/logs` Access: `read` · MCP tool: `list-comment-automation-logs` · Zernio: `GET /v1/comment-automations/{automationId}/logs` ### Path parameters - `id` (string; required; 1–80 characters): commentAutomation id (cau_…) ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `status` (string) - `source` (string) ```bash curl "https://api.socialit.com/v1/comment-automations/cau_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/logs" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "comment_automation_log", "id": "string", "automation_id": "string", "comment_id": "string", "commenter_id": "string", "commenter_name": "string", "commenter_username": "string", "comment_text": "string", "source": "string", "status": "pending", "skip_reason": "string", "contact_id": "string", "audience_outcome": "string", "commenter_is_follower": true, "commenter_follower_count": 1, "dm_message_id": "string", "error": "string", "platform_error": { "code": 1, "subcode": 1 }, "private_reply_consumed": true, "comment_reply_status": "string", "comment_reply_error": "string", "public_reply_posted_at": "2026-10-13T09:00:00.000Z", "like_skipped": "string", "hide_skipped": "string", "media_error": "string", "next_due_at": "2026-10-13T09:00:00.000Z", "clicked_at": "2026-10-13T09:00:00.000Z", "click_count": 1, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` --- Source: https://socialit.com/docs/api-reference/comment-automations/ # Ads API > Unified ads across Meta, Google, LinkedIn, TikTok, Pinterest, X, Reddit and OpenAI (ChatGPT) Ads: connections, campaigns, ad sets, ads, creatives, insights, targeting, audiences, Google Ads specifics, Ad Library, Reach & Frequency. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## Connect ads for a platform `GET /connect/{platform}/ads` Starts an ads connection. Returns the network authorization URL (ads_connect_url), or connects at once (ads_connect_result) when a posting account (account_id) already carries the ads scopes or the connection already exists (unless force). Access: `write` · MCP tool: `connect-ads` · Zernio: `GET /v1/connect/{platform}/ads` ### Path parameters - `platform` (string; required; 1–40 characters) ### Query parameters - `profile_id` (string) - `account_id` (string) - `login_mode` (string; one of classic, business) - `permission_level` (string; one of full, advertise) - `page_id` (string) - `ad_account_id` (string) - `ad_account_ids` (string) - `redirect_url` (string) - `headless` (boolean) - `force` (boolean) ```bash curl "https://api.socialit.com/v1/connect/PLATFORM/ads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ads_connect_url", "platform": "string", "login_mode": "string", "url": "https://example.com", "auth_url": "https://example.com", "state": "string", "expires_at": "2026-10-13T09:00:00.000Z" } ``` ## Ads OAuth redirect target `GET /connect/ads/{platform}/callback` Browser redirect target of every ads OAuth flow (Google, TikTok, LinkedIn, Pinterest, Reddit, X, Meta classic). Redirects to the caller redirect_url or the dashboard. Access: `read` ### Path parameters - `platform` (string; required) ### Query parameters - `state` (string) - `code` (string) - `auth_code` (string) - `error` (string) - `error_description` (string) - `oauth_token` (string) - `oauth_verifier` (string) ```bash curl "https://api.socialit.com/v1/connect/ads/PLATFORM/callback" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` ## Complete Meta business login `GET /connect/meta-ads/callback` Facebook Login for Business redirect target (system-user token). Access: `read` · Zernio: `GET /v1/connect/meta-ads/callback` ### Query parameters - `state` (string; required) - `code` (string) - `error` (string) ```bash curl "https://api.socialit.com/v1/connect/meta-ads/callback?state=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` ## Set TikTok brand identity `PATCH /connect/tiktok-ads` Access: `write` · MCP tool: `set-tiktok-ads-brand-identity` · Zernio: `PATCH /v1/connect/tiktok-ads` ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `display_name` (string; required; 1–40 characters) - `image_url` (string (uri); required) ```bash curl -X PATCH "https://api.socialit.com/v1/connect/tiktok-ads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "display_name": "string", "image_url": "https://example.com" }' ``` Response 200: ```json { "object": "tiktok_brand_identity" } ``` ## Connect an OpenAI (ChatGPT) Ads account `POST /connect/openai-ads/credentials` Access: `write` · MCP tool: `connect-openai-ads` · Zernio: `POST /v1/connect/openai-ads/credentials` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `api_key` (string; required; 8–500 characters) - `profile_id` (string) - `redirect_url` (string) - `redirect_uri` (string) - `state` (string) ```bash curl -X POST "https://api.socialit.com/v1/connect/openai-ads/credentials" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "api_key": "xxxxxxxx", "profile_id": "string", "redirect_url": "https://example.com", "redirect_uri": "https://example.com", "state": "string" }' ``` Response 200: ```json { "object": "ads_connect_result", "status": "string", "already_connected": true, "platform": "string", "profile_id": "string", "connection": { "object": "ad_connection", "id": "string", "platform": "string", "ad_accounts": [ {} ] }, "ad_accounts": [ { "object": "ad_account", "id": "string" } ], "redirect_url": "https://example.com" } ``` ## Connect a Whop account `POST /connect/whop-ads/credentials` Access: `write` · MCP tool: `connect-whop-ads` · Zernio: `POST /v1/connect/whop-ads/credentials` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `api_key` (string; required; 8–500 characters) - `profile_id` (string) - `redirect_url` (string) - `state` (string) ```bash curl -X POST "https://api.socialit.com/v1/connect/whop-ads/credentials" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "api_key": "xxxxxxxx", "profile_id": "string", "redirect_url": "https://example.com", "state": "string" }' ``` Response 200: ```json { "object": "ads_connect_result", "status": "string", "already_connected": true, "platform": "string", "profile_id": "string", "connection": { "object": "ad_connection", "id": "string", "platform": "string", "ad_accounts": [ {} ] }, "ad_accounts": [ { "object": "ad_account", "id": "string" } ], "redirect_url": "https://example.com" } ``` ## List ads connections `GET /ads/connections` Access: `read` · MCP tool: `list-ad-connections` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, platform, status) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `profile_id` (string) - `status` (string; one of active, needs_reconnect, disconnected) ```bash curl "https://api.socialit.com/v1/ads/connections" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_connection", "id": "string", "platform": "string", "ad_accounts": [ {} ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get an ads connection `GET /ads/connections/{id}` Access: `read` · MCP tool: `get-ad-connection` ### Path parameters - `id` (string; required; 1–300 characters) ```bash curl "https://api.socialit.com/v1/ads/connections/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_connection", "id": "string", "platform": "string", "ad_accounts": [ {} ] } ``` ## Disconnect an ads connection `DELETE /ads/connections/{id}` Access: `write` · MCP tool: `delete-ad-connection` ### Path parameters - `id` (string; required; 1–300 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/connections/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_connection", "id": "string", "deleted": true, "token_revoked": true } ``` ## Queue an ads sync `POST /ads/connections/{id}/sync` Access: `write` · MCP tool: `sync-ad-connection` ### Path parameters - `id` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `backfill` (boolean) - `ad_account_ids` (array of string) ```bash curl -X POST "https://api.socialit.com/v1/ads/connections/ID/sync" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "backfill": true, "ad_account_ids": [ "string" ] }' ``` Response 202: ```json { "object": "ad_sync", "connection_id": "string", "status": "string", "backfill": true, "job_id": "string" } ``` ## List ads `GET /ads` Access: `read` · MCP tool: `list-ads` · Zernio: `GET /v1/ads` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name, status, updated_at, spend, impressions) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `source` (string; one of all, socialit, external) - `status` (string) - `profile_id` (string) - `campaign_id` (string) - `ad_set_id` (string) - `search` (string) - `has_delivery` (boolean) - `min_spend` (number) - `platform_ad_id` (string) - `post_id` (string) - `platform_post_id` (string) ```bash curl "https://api.socialit.com/v1/ads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5 }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "network": "string", "campaign_id": "string", "ad_set_id": "string", "campaign_external_id": "string", "ad_set_external_id": "string", "campaign_name": "string", "ad_set_name": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "backfill_pending": true } ``` ## Create an ad (full tree) `POST /ads` Builds campaign → ad set → creative → ad in one call, or attaches to an existing campaign (existing_campaign_id) or ad set (ad_set_id). validate_only: true dry-runs (Meta, Google, OpenAI). Access: `write` · MCP tool: `create-ad` · Zernio: `POST /v1/ads/create` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string; required; 1–400 characters) - `campaign_name` (string) - `ad_set_name` (string) - `ad_name` (string) - `goal` (string; one of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants) - `existing_campaign_id` (string) - `ad_set_id` (string) - `status` (string; one of active, paused) - `campaign_status` (string; one of active, paused) - `ad_set_status` (string; one of active, paused) - `ad_status` (string; one of active, paused) - `budget` (object) - `budget.amount` (number; required) - `budget.type` (string; one of daily, lifetime) - `budget_amount` (number) - `budget_type` (string; one of daily, lifetime) - `budget_level` (string; one of campaign, ad_set) - `currency` (string) - `start_time` (string) - `end_time` (string) - `bid_strategy` (string) - `bid_amount` (number) - `roas_average_floor` (number) - `optimization_goal` (string) - `billing_event` (string) - `buying_type` (string) - `rf_prediction_id` (string) - `special_ad_categories` (array of string) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, … - `creatives` (array of object; ≤ 50 items) - `optimize_card_order` (boolean): Meta carousels: false keeps your card order (max 5 cards); omit for Meta's default (true). Only with carousel_cards. - `page_id` (string) - `instagram_account_id` (string) - `identity_id` (string) - `identity_type` (string) - `organization_id` (string) - `board_id` (string) - `lead_gen_form_id` (string) - `phone_number` (string) - `campaign_type` (string; one of search, display, performance_max, demand_gen, video) - `keywords` (array of object) - `negative_keywords` (array of object) - `headlines` (array of any) - `long_headline` (string) - `descriptions` (array of any) - `business_name` (string) - `asset_group` (object) - `demand_gen` (object) - `tracking` (object) - `platform_specific_data` (object) - `validate_only` (boolean) - `post_id` (string) - `platform_post_id` (string) - `link_url` (string) - `body` (string) - `headline` (string) - `image_url` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "campaign_name": "string" }' ``` Response 200: ```json { "object": "ad_validation", "valid": true, "platform": "string", "results": [ {} ] } ``` ## List campaigns `GET /ads/campaigns` Access: `read` · MCP tool: `list-ad-campaigns` · Zernio: `GET /v1/ads/campaigns` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name, status, updated_at, spend, impressions) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `source` (string; one of all, socialit, external) - `status` (string) - `profile_id` (string) - `campaign_id` (string) - `ad_set_id` (string) - `search` (string) - `has_delivery` (boolean) - `min_spend` (number) - `include_empty` (boolean) - `live` (boolean) ```bash curl "https://api.socialit.com/v1/ads/campaigns" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_campaign", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5 }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "goal": "string", "objective": "string", "review_status": "string", "buying_type": "string", "channel_type": "string", "is_smart_plus": true, "roas_average_floor": 1.5 } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "backfill_pending": true } ``` ## Create a campaign `POST /ads/campaigns` Access: `write` · MCP tool: `create-ad-campaign` · Zernio: `POST /v1/ads/campaigns` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string; required; 1–400 characters) - `goal` (string; required; one of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants) - `status` (string; one of active, paused) - `budget` (object) - `budget.amount` (number; required) - `budget.type` (string; one of daily, lifetime) - `budget_amount` (number) - `budget_type` (string; one of daily, lifetime) - `budget_level` (string; one of campaign, ad_set) - `buying_type` (string; one of AUCTION, RESERVED) - `special_ad_categories` (array of string) - `special_ad_category_country` (array of string) - `promoted_object` (object) - `is_skadnetwork_attribution` (boolean) - `start_time` (string) - `end_time` (string) - `bid_strategy` (string) - `bid_amount` (number) - `roas_average_floor` (number) - `portfolio_bid_strategy_id` (string) - `target_impression_share` (object) - `manual_cpc` (object) - `network_settings` (object) - `location_targeting_type` (string) - `campaign_type` (string; one of search, display, performance_max, demand_gen) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `shared_budget_id` (string) - `platform_specific_data` (object) - `validate_only` (boolean) - `funding_instrument_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/campaigns" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "goal": "engagement" }' ``` Response 200: ```json { "object": "ad_validation", "valid": true, "platform": "string", "results": [ {} ] } ``` ## List ad sets `GET /ads/ad-sets` Access: `read` · MCP tool: `list-ad-sets` · Zernio: `GET /v1/ads/ad-sets` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name, status, updated_at, spend, impressions) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `source` (string; one of all, socialit, external) - `status` (string) - `profile_id` (string) - `campaign_id` (string) - `ad_set_id` (string) - `search` (string) - `has_delivery` (boolean) - `min_spend` (number) - `live` (boolean) ```bash curl "https://api.socialit.com/v1/ads/ad-sets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_set", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5 }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "campaign_id": "string", "campaign_external_id": "string", "is_smart_plus": true, "roas_average_floor": 1.5, "optimization_goal": "string", "billing_event": "string", "targeting": {} } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "backfill_pending": true } ``` ## Create an ad set `POST /ads/ad-sets` Access: `write` · MCP tool: `create-ad-set` · Zernio: `POST /v1/ads/ad-sets` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `campaign_id` (string; required) - `name` (string; required; 1–400 characters) - `status` (string; one of active, paused) - `budget` (object) - `budget.amount` (number; required) - `budget.type` (string; one of daily, lifetime) - `bid_amount` (number) - `max_cpc` (number) - `bid_strategy` (string) - `optimization_goal` (string) - `billing_event` (string) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `start_time` (string) - `end_time` (string) - `promoted_object` (object) - `customer_id` (string) - `platform_specific_data` (object) ```bash curl -X POST "https://api.socialit.com/v1/ads/ad-sets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "campaign_id": "string", "name": "string" }' ``` Response 201: ```json { "object": "ad_set", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {}, "currency": "USD", "last_synced_at": "2026-10-13T09:00:00.000Z" }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "campaign_id": "string", "campaign_external_id": "string", "is_smart_plus": true, "roas_average_floor": 1.5, "optimization_goal": "string", "billing_event": "string", "targeting": {}, "promoted_object": {}, "learning_phase": "string", "ad_count": 1, "settings": {}, "ads": [ { "object": "ad", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5 }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "network": "string", "campaign_id": "string", "ad_set_id": "string", "campaign_external_id": "string", "ad_set_external_id": "string", "campaign_name": "string", "ad_set_name": "string" } ], "daily": [ { "date": "string", "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {} } ] } ``` ## Get the campaign tree `GET /ads/tree` Access: `read` · MCP tool: `get-ad-tree` · Zernio: `GET /v1/ads/tree` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name, status, updated_at, spend, impressions) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `source` (string; one of all, socialit, external) - `status` (string) - `profile_id` (string) - `campaign_id` (string) - `ad_set_id` (string) - `search` (string) - `has_delivery` (boolean) - `min_spend` (number) - `updated_since` (string) - `daily` (boolean) - `daily_level` (string) - `time_increment` (string) ```bash curl "https://api.socialit.com/v1/ads/tree" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_campaign", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5 }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "goal": "string", "objective": "string", "review_status": "string", "buying_type": "string", "channel_type": "string", "is_smart_plus": true, "roas_average_floor": 1.5 } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "backfill_pending": true } ``` ## Get daily account metrics `GET /ads/timeline` Access: `read` · MCP tool: `get-ad-timeline` · Zernio: `GET /v1/ads/timeline` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) ```bash curl "https://api.socialit.com/v1/ads/timeline" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_timeline", "currency": "USD", "from_date": "string", "to_date": "string", "backfill_pending": true, "data": [ { "date": "string", "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {} } ] } ``` ## Get campaign details `GET /ads/campaigns/{id}` Access: `read` · MCP tool: `get-ad-campaign` · Zernio: `GET /v1/ads/campaigns/{campaignId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `live` (boolean) - `fields` (string) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_campaign", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {}, "currency": "USD", "last_synced_at": "2026-10-13T09:00:00.000Z" }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "goal": "string", "objective": "string", "review_status": "string", "buying_type": "string", "channel_type": "string", "is_smart_plus": true, "roas_average_floor": 1.5, "special_ad_categories": [ "string" ], "ad_set_count": 1, "ad_count": 1, "settings": {}, "issues": [ {} ], "ad_sets": [ { "object": "ad_set", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5 }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "campaign_id": "string", "campaign_external_id": "string", "is_smart_plus": true, "roas_average_floor": 1.5, "optimization_goal": "string", "billing_event": "string", "targeting": {} } ], "daily": [ { "date": "string", "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {} } ] } ``` ## Update a campaign `PATCH /ads/campaigns/{id}` Access: `write` · MCP tool: `update-ad-campaign` · Zernio: `PUT /v1/ads/campaigns/{campaignId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `name` (string; 1–400 characters) - `budget` (object) - `budget.amount` (number; required) - `budget.type` (string; one of daily, lifetime) - `shared_budget_id` (string) - `allow_shared_budget_update` (boolean) - `bid_strategy` (string) - `bid_amount` (number) - `roas_average_floor` (number) - `portfolio_bid_strategy_id` (string) - `target_impression_share` (object) - `manual_cpc` (object) - `network_settings` (object) - `tracking_url_template` (string) - `final_url_suffix` (string) - `start_time` (string) - `end_time` (string) - `spend_cap` (number | null) - `platform_specific_data` (object) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/campaigns/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "name": "string" }' ``` Response 200: ```json { "object": "ad_campaign", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {}, "currency": "USD", "last_synced_at": "2026-10-13T09:00:00.000Z" }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "goal": "string", "objective": "string", "review_status": "string", "buying_type": "string", "channel_type": "string", "is_smart_plus": true, "roas_average_floor": 1.5, "special_ad_categories": [ "string" ], "ad_set_count": 1, "ad_count": 1, "settings": {}, "issues": [ {} ], "ad_sets": [ { "object": "ad_set", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5 }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "campaign_id": "string", "campaign_external_id": "string", "is_smart_plus": true, "roas_average_floor": 1.5, "optimization_goal": "string", "billing_event": "string", "targeting": {} } ], "daily": [ { "date": "string", "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {} } ] } ``` ## Delete a campaign `DELETE /ads/campaigns/{id}` Access: `write` · MCP tool: `delete-ad-campaign` · Zernio: `DELETE /v1/ads/campaigns/{campaignId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/campaigns/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_campaign", "id": "string", "deleted": true, "archived": true } ``` ## Pause or resume a campaign `PATCH /ads/campaigns/{id}/status` Access: `write` · MCP tool: `set-ad-campaign-status` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/status` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `status` (string; required; one of active, paused) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/campaigns/ID/status" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "status": "active", "platform": "string" }' ``` Response 200: ```json { "object": "ad_status_change", "level": "string", "id": "string", "external_id": "string", "platform": "string", "status": "string", "platform_status": "string", "updated": true, "skipped": true, "skipped_reasons": [ "string" ] } ``` ## Pause or resume many campaigns `POST /ads/campaigns/bulk-status` Access: `write` · MCP tool: `bulk-set-ad-campaign-status` · Zernio: `POST /v1/ads/campaigns/bulk-status` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `status` (string; required; one of active, paused) - `campaigns` (array of object; required; 1–50 items) - `campaigns[].id` (string; required) - `campaigns[].platform` (string) - `campaigns[].ad_account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/campaigns/bulk-status" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "status": "active", "campaigns": [ { "id": "string", "platform": "string" } ] }' ``` Response 200: ```json { "object": "ad_bulk_status", "status": "string", "totals": { "updated": 1, "skipped": 1, "failed": 1 }, "results": [ { "id": "string", "external_id": "string", "platform": "string", "updated": true, "skipped": true, "platform_status": "string", "error": "string" } ] } ``` ## Duplicate a campaign `POST /ads/campaigns/{id}/duplicate` Access: `write` · MCP tool: `duplicate-ad-campaign` · Zernio: `POST /v1/ads/campaigns/{campaignId}/duplicate` ### Path parameters - `id` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `deep_copy` (boolean) - `status_option` (string; one of paused, active, inherited) - `start_time` (string) - `end_time` (string) - `rename_strategy` (string; one of none, prefix, suffix, deep_rename) - `rename_prefix` (string) - `rename_suffix` (string) - `sync_after` (boolean) - `campaign_id` (string) - `ad_set_id` (string) - `reuse_source_creative` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/campaigns/ID/duplicate" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "deep_copy": true }' ``` Response 201: ```json { "object": "ad_duplicate", "level": "string", "source_id": "string", "copied_external_id": "string", "copied_id": "string", "sync": "string", "raw": {} } ``` ## Get campaign analytics `GET /ads/campaigns/{id}/analytics` Access: `read` · MCP tool: `get-ad-campaign-analytics` · Zernio: `GET /v1/ads/campaigns/{campaignId}/analytics` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `breakdowns` (string) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID/analytics" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_analytics", "level": "string", "id": "string", "platform": "string", "name": "string", "status": "string", "currency": "USD", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "from_date": "string", "to_date": "string", "backfill_pending": true, "summary": {}, "daily": [ { "date": "string", "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {} } ], "breakdowns": {}, "unsupported_breakdowns": [ "string" ], "breakdown_hints": {}, "breakdown_errors": {}, "breakdown_dropped_metrics": {}, "breakdowns_range": { "from": "+15551234567", "to": "+15551234567" } } ``` ## Read a campaign's bidding `GET /ads/campaigns/{id}/bidding` Access: `read` · MCP tool: `get-ad-campaign-bidding` · Zernio: `GET /v1/ads/campaigns/{campaignId}/bidding` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `customer_id` (string) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID/bidding" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "campaign_bidding" } ``` ## Read a campaign's ad schedule `GET /ads/campaigns/{id}/ad-schedule` Access: `read` · MCP tool: `get-ad-campaign-schedule` · Zernio: `GET /v1/ads/campaigns/{campaignId}/ad-schedule` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `include_performance` (boolean) - `window_days` (integer; 1–90) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID/ad-schedule" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_schedule" } ``` ## Replace a campaign's ad schedule `PUT /ads/campaigns/{id}/ad-schedule` Access: `write` · MCP tool: `replace-ad-campaign-schedule` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/ad-schedule` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `schedule` (array of object; required; ≤ 42 items) - `schedule[].day_of_week` (string; required; one of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY) - `schedule[].start_hour` (integer; required; 0–23) - `schedule[].start_minute` (integer; one of 0, 15, 30, 45) - `schedule[].end_hour` (integer; required; 0–24) - `schedule[].end_minute` (integer; one of 0, 15, 30, 45) - `schedule[].bid_modifier` (number) ```bash curl -X PUT "https://api.socialit.com/v1/ads/campaigns/ID/ad-schedule" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "schedule": [ { "day_of_week": "MONDAY", "start_hour": 0, "end_hour": 0 } ] }' ``` Response 200: ```json { "object": "ad_schedule" } ``` ## Read a Google campaign's targeting `GET /ads/campaigns/{id}/targeting` Access: `read` · MCP tool: `get-ad-campaign-targeting` · Zernio: `GET /v1/ads/campaigns/{campaignId}/targeting` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID/targeting" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "campaign_targeting" } ``` ## Edit a Google campaign's targeting `PUT /ads/campaigns/{id}/targeting` Access: `write` · MCP tool: `replace-ad-campaign-targeting` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/targeting` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `targeting` (object; required) - `targeting.devices` (array of object) - `targeting.locations` (array of object) - `targeting.excluded_locations` (array of object) - `targeting.languages` (array of object) ```bash curl -X PUT "https://api.socialit.com/v1/ads/campaigns/ID/targeting" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "targeting": { "devices": [ {} ], "locations": [ {} ] } }' ``` Response 200: ```json { "object": "campaign_targeting" } ``` ## List campaign negative keywords `GET /ads/campaigns/{id}/negative-keywords` Access: `read` · MCP tool: `list-ad-campaign-negative-keywords` · Zernio: `GET /v1/ads/campaigns/{campaignId}/negative-keywords` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID/negative-keywords" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "negative_keyword" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Replace campaign negative keywords `PUT /ads/campaigns/{id}/negative-keywords` Access: `write` · MCP tool: `replace-ad-campaign-negative-keywords` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/negative-keywords` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `keywords` (array of object; required; ≤ 5000 items) - `keywords[].text` (string; required; 1–80 characters) - `keywords[].match_type` (string; one of exact, phrase, broad) ```bash curl -X PUT "https://api.socialit.com/v1/ads/campaigns/ID/negative-keywords" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "keywords": [ { "text": "string", "match_type": "exact" } ] }' ``` Response 200: ```json { "object": "list", "data": [ { "object": "negative_keyword" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## List campaign negative keyword lists `GET /ads/campaigns/{id}/negative-keyword-lists` Access: `read` · MCP tool: `list-ad-campaign-negative-keyword-lists` · Zernio: `GET /v1/ads/campaigns/{campaignId}/negative-keyword-lists` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID/negative-keyword-lists" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "negative_keyword_list" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Replace campaign negative keyword lists `PUT /ads/campaigns/{id}/negative-keyword-lists` Access: `write` · MCP tool: `replace-ad-campaign-negative-keyword-lists` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/negative-keyword-lists` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `list_ids` (array of string; required; ≤ 20 items) ```bash curl -X PUT "https://api.socialit.com/v1/ads/campaigns/ID/negative-keyword-lists" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "list_ids": [ "string" ] }' ``` Response 200: ```json { "object": "list", "data": [ { "object": "negative_keyword_list" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## List campaign assets `GET /ads/campaigns/{id}/assets` Access: `read` · MCP tool: `list-ad-campaign-assets` · Zernio: `GET /v1/ads/campaigns/{campaignId}/assets` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `customer_id` (string) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID/assets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_asset" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Attach campaign assets `POST /ads/campaigns/{id}/assets` Access: `write` · MCP tool: `add-ad-campaign-assets` · Zernio: `POST /v1/ads/campaigns/{campaignId}/assets` ### Path parameters - `id` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `sitelinks` (array of object; ≤ 50 items) - `callouts` (array of object; ≤ 50 items) - `structured_snippets` (array of object; ≤ 20 items) - `images` (array of object; ≤ 20 items) - `customer_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/campaigns/ID/assets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "sitelinks": [ {} ], "callouts": [ {} ] }' ``` Response 201: ```json { "object": "list", "data": [ { "object": "ad_asset" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Update campaign assets `PATCH /ads/campaigns/{id}/assets` Access: `write` · MCP tool: `update-ad-campaign-assets` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/assets` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `updates` (array of object; required; 1–100 items) - `customer_id` (string) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/campaigns/ID/assets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "updates": [ {} ], "customer_id": "string" }' ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_asset" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Remove campaign assets `DELETE /ads/campaigns/{id}/assets` Access: `write` · MCP tool: `remove-ad-campaign-assets` · Zernio: `DELETE /v1/ads/campaigns/{campaignId}/assets` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `asset_ids` (string) - `link_ids` (string) - `customer_id` (string) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/campaigns/ID/assets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_asset_removal", "removed": 1 } ``` ## Get campaign conversion goals `GET /ads/campaigns/{id}/conversion-goals` Access: `read` · MCP tool: `get-ad-campaign-conversion-goals` · Zernio: `GET /v1/ads/campaigns/{campaignId}/conversion-goals` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID/conversion-goals" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "campaign_conversion_goals" } ``` ## Update campaign conversion goals `PATCH /ads/campaigns/{id}/conversion-goals` Access: `write` · MCP tool: `update-ad-campaign-conversion-goals` · Zernio: `PATCH /v1/ads/campaigns/{campaignId}/conversion-goals` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `goals` (array of object; ≤ 50 items) - `goals[].category` (string; required) - `goals[].origin` (string; required) - `goals[].biddable` (boolean; required) - `goal_config_level` (string; one of customer, campaign) - `custom_conversion_goal_id` (string | null) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/campaigns/ID/conversion-goals" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "goals": [ { "category": "string", "origin": "string", "biddable": true } ] }' ``` Response 200: ```json { "object": "campaign_conversion_goals" } ``` ## List Performance Max asset groups `GET /ads/campaigns/{id}/asset-groups` Access: `read` · MCP tool: `list-ad-asset-groups` · Zernio: `GET /v1/ads/campaigns/{campaignId}/asset-groups` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "asset_group" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a Performance Max asset group `POST /ads/campaigns/{id}/asset-groups` Access: `write` · MCP tool: `create-ad-asset-group` · Zernio: `POST /v1/ads/campaigns/{campaignId}/asset-groups` ### Path parameters - `id` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `name` (string; required; 1–255 characters) - `final_urls` (array of string; required; ≥ 1 items) - `final_mobile_urls` (array of string) - `path1` (string) - `path2` (string) - `status` (string; one of enabled, paused) - `assets` (object) - `listing_group_filter` (object) - `validate_only` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "final_urls": [ "string" ] }' ``` Response 200: ```json { "object": "ad_validation", "valid": true, "platform": "string", "results": [ {} ] } ``` ## Get a Performance Max asset group `GET /ads/campaigns/{id}/asset-groups/{assetGroupId}` Access: `read` · MCP tool: `get-ad-asset-group` · Zernio: `GET /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}` ### Path parameters - `id` (string; required; 1–300 characters) - `assetGroupId` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups/ASSET_GROUP_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "asset_group" } ``` ## Update a Performance Max asset group `PATCH /ads/campaigns/{id}/asset-groups/{assetGroupId}` Access: `write` · MCP tool: `update-ad-asset-group` · Zernio: `PATCH /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}` ### Path parameters - `id` (string; required; 1–300 characters) - `assetGroupId` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `name` (string) - `status` (string; one of enabled, paused) - `final_urls` (array of string) - `final_mobile_urls` (array of string) - `path1` (string) - `path2` (string) - `validate_only` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups/ASSET_GROUP_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "name": "string" }' ``` Response 200: ```json { "object": "asset_group" } ``` ## Remove a Performance Max asset group `DELETE /ads/campaigns/{id}/asset-groups/{assetGroupId}` Access: `write` · MCP tool: `delete-ad-asset-group` · Zernio: `DELETE /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}` ### Path parameters - `id` (string; required; 1–300 characters) - `assetGroupId` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `validate_only` (boolean) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups/ASSET_GROUP_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "asset_group", "id": "string", "deleted": true, "archived": true } ``` ## Link or unlink asset group assets `POST /ads/campaigns/{id}/asset-groups/{assetGroupId}/assets` Access: `write` · MCP tool: `link-ad-asset-group-assets` · Zernio: `POST /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}/assets` ### Path parameters - `id` (string; required; 1–300 characters) - `assetGroupId` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `link` (array of object; ≤ 100 items) - `unlink` (array of object; ≤ 100 items) - `validate_only` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups/ASSET_GROUP_ID/assets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "link": [ {} ] }' ``` Response 200: ```json { "object": "asset_group" } ``` ## Replace an asset group's listing-group tree `PUT /ads/campaigns/{id}/asset-groups/{assetGroupId}/listing-group-filters` Access: `write` · MCP tool: `replace-ad-listing-group-filters` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}/listing-group-filters` ### Path parameters - `id` (string; required; 1–300 characters) - `assetGroupId` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `tree` (object; required) - `validate_only` (boolean) ```bash curl -X PUT "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups/ASSET_GROUP_ID/listing-group-filters" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "tree": {} }' ``` Response 200: ```json { "object": "listing_group_tree" } ``` ## Get ad set details `GET /ads/ad-sets/{id}` Access: `read` · MCP tool: `get-ad-set` · Zernio: `GET /v1/ads/ad-sets/{adSetId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `live` (boolean) - `fields` (string) ```bash curl "https://api.socialit.com/v1/ads/ad-sets/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_set", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {}, "currency": "USD", "last_synced_at": "2026-10-13T09:00:00.000Z" }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "campaign_id": "string", "campaign_external_id": "string", "is_smart_plus": true, "roas_average_floor": 1.5, "optimization_goal": "string", "billing_event": "string", "targeting": {}, "promoted_object": {}, "learning_phase": "string", "ad_count": 1, "settings": {}, "ads": [ { "object": "ad", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5 }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "network": "string", "campaign_id": "string", "ad_set_id": "string", "campaign_external_id": "string", "ad_set_external_id": "string", "campaign_name": "string", "ad_set_name": "string" } ], "daily": [ { "date": "string", "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {} } ] } ``` ## Update an ad set `PATCH /ads/ad-sets/{id}` Access: `write` · MCP tool: `update-ad-set` · Zernio: `PUT /v1/ads/ad-sets/{adSetId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `name` (string) - `status` (string; one of active, paused) - `budget` (object) - `budget.amount` (number; required) - `budget.type` (string; one of daily, lifetime) - `bid_strategy` (string) - `bid_amount` (number) - `roas_average_floor` (number) - `smart_targeting` (boolean) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `start_time` (string) - `end_time` (string) - `value_rule_set_id` (string) - `value_rules_applied` (boolean) - `optimization_goal` (string) - `platform_specific_data` (object) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/ad-sets/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "name": "string" }' ``` Response 200: ```json { "object": "ad_set", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {}, "currency": "USD", "last_synced_at": "2026-10-13T09:00:00.000Z" }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "campaign_id": "string", "campaign_external_id": "string", "is_smart_plus": true, "roas_average_floor": 1.5, "optimization_goal": "string", "billing_event": "string", "targeting": {}, "promoted_object": {}, "learning_phase": "string", "ad_count": 1, "settings": {}, "ads": [ { "object": "ad", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5 }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "network": "string", "campaign_id": "string", "ad_set_id": "string", "campaign_external_id": "string", "ad_set_external_id": "string", "campaign_name": "string", "ad_set_name": "string" } ], "daily": [ { "date": "string", "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {} } ] } ``` ## Delete an ad set `DELETE /ads/ad-sets/{id}` Access: `write` · MCP tool: `delete-ad-set` · Zernio: `DELETE /v1/ads/ad-sets/{adSetId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/ad-sets/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_set", "id": "string", "deleted": true, "archived": true } ``` ## Pause or resume an ad set `PATCH /ads/ad-sets/{id}/status` Access: `write` · MCP tool: `set-ad-set-status` · Zernio: `PUT /v1/ads/ad-sets/{adSetId}/status` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `status` (string; required; one of active, paused) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/ad-sets/ID/status" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "status": "active", "platform": "string" }' ``` Response 200: ```json { "object": "ad_status_change", "level": "string", "id": "string", "external_id": "string", "platform": "string", "status": "string", "platform_status": "string", "updated": true, "skipped": true, "skipped_reasons": [ "string" ] } ``` ## Duplicate an ad set `POST /ads/ad-sets/{id}/duplicate` Access: `write` · MCP tool: `duplicate-ad-set` · Zernio: `POST /v1/ads/ad-sets/{adSetId}/duplicate` ### Path parameters - `id` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `deep_copy` (boolean) - `status_option` (string; one of paused, active, inherited) - `start_time` (string) - `end_time` (string) - `rename_strategy` (string; one of none, prefix, suffix, deep_rename) - `rename_prefix` (string) - `rename_suffix` (string) - `sync_after` (boolean) - `campaign_id` (string) - `ad_set_id` (string) - `reuse_source_creative` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/ad-sets/ID/duplicate" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "deep_copy": true }' ``` Response 201: ```json { "object": "ad_duplicate", "level": "string", "source_id": "string", "copied_external_id": "string", "copied_id": "string", "sync": "string", "raw": {} } ``` ## List ad-group assets `GET /ads/ad-sets/{id}/assets` Access: `read` · MCP tool: `list-ad-set-assets` · Zernio: `GET /v1/ads/ad-sets/{adSetId}/assets` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `customer_id` (string) ```bash curl "https://api.socialit.com/v1/ads/ad-sets/ID/assets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_asset" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Attach ad-group assets `POST /ads/ad-sets/{id}/assets` Access: `write` · MCP tool: `add-ad-set-assets` · Zernio: `POST /v1/ads/ad-sets/{adSetId}/assets` ### Path parameters - `id` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `sitelinks` (array of object; ≤ 50 items) - `callouts` (array of object; ≤ 50 items) - `structured_snippets` (array of object; ≤ 20 items) - `images` (array of object; ≤ 20 items) - `customer_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/ad-sets/ID/assets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "sitelinks": [ {} ], "callouts": [ {} ] }' ``` Response 201: ```json { "object": "list", "data": [ { "object": "ad_asset" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Update ad-group assets `PATCH /ads/ad-sets/{id}/assets` Access: `write` · MCP tool: `update-ad-set-assets` · Zernio: `PUT /v1/ads/ad-sets/{adSetId}/assets` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `updates` (array of object; required; 1–100 items) - `customer_id` (string) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/ad-sets/ID/assets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "updates": [ {} ], "customer_id": "string" }' ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_asset" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Remove ad-group assets `DELETE /ads/ad-sets/{id}/assets` Access: `write` · MCP tool: `remove-ad-set-assets` · Zernio: `DELETE /v1/ads/ad-sets/{adSetId}/assets` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `asset_ids` (string) - `link_ids` (string) - `customer_id` (string) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/ad-sets/ID/assets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_asset_removal", "removed": 1 } ``` ## Boost a post as an ad `POST /ads/boost` Access: `write` · MCP tool: `boost-ad-post` · Zernio: `POST /v1/ads/boost` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string; required; 1–400 characters) - `campaign_name` (string) - `ad_set_name` (string) - `ad_name` (string) - `goal` (string; required; one of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants) - `existing_campaign_id` (string) - `ad_set_id` (string) - `status` (string; one of active, paused) - `campaign_status` (string; one of active, paused) - `ad_set_status` (string; one of active, paused) - `ad_status` (string; one of active, paused) - `budget` (object) - `budget.amount` (number; required) - `budget.type` (string; one of daily, lifetime) - `budget_amount` (number) - `budget_type` (string; one of daily, lifetime) - `budget_level` (string; one of campaign, ad_set) - `currency` (string) - `start_time` (string) - `end_time` (string) - `bid_strategy` (string) - `bid_amount` (number) - `roas_average_floor` (number) - `optimization_goal` (string) - `billing_event` (string) - `buying_type` (string) - `rf_prediction_id` (string) - `special_ad_categories` (array of string) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, … - `creatives` (array of object; ≤ 50 items) - `optimize_card_order` (boolean): Meta carousels: false keeps your card order (max 5 cards); omit for Meta's default (true). Only with carousel_cards. - `page_id` (string) - `instagram_account_id` (string) - `identity_id` (string) - `identity_type` (string) - `organization_id` (string) - `board_id` (string) - `lead_gen_form_id` (string) - `phone_number` (string) - `campaign_type` (string; one of search, display, performance_max, demand_gen, video) - `keywords` (array of object) - `negative_keywords` (array of object) - `headlines` (array of any) - `long_headline` (string) - `descriptions` (array of any) - `business_name` (string) - `asset_group` (object) - `demand_gen` (object) - `tracking` (object) - `platform_specific_data` (object) - `validate_only` (boolean) - `post_id` (string) - `platform_post_id` (string) - `link_url` (string) - `body` (string) - `headline` (string) - `image_url` (string) - `destination_type` (string; one of WEBSITE, MESSENGER, INSTAGRAM_DIRECT) - `spark_auth_code` (string) - `call_to_action` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/boost" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "goal": "engagement" }' ``` Response 200: ```json { "object": "ad_validation", "valid": true, "platform": "string", "results": [ {} ] } ``` ## Create a click-to-message ad `POST /ads/messaging` Access: `write` · MCP tool: `create-messaging-ad` · Zernio: `POST /v1/ads/messaging` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string; required; 1–400 characters) - `campaign_name` (string) - `ad_set_name` (string) - `ad_name` (string) - `goal` (string; one of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants) - `existing_campaign_id` (string) - `ad_set_id` (string) - `status` (string; one of active, paused) - `campaign_status` (string; one of active, paused) - `ad_set_status` (string; one of active, paused) - `ad_status` (string; one of active, paused) - `budget` (object) - `budget.amount` (number; required) - `budget.type` (string; one of daily, lifetime) - `budget_amount` (number) - `budget_type` (string; one of daily, lifetime) - `budget_level` (string; one of campaign, ad_set) - `currency` (string) - `start_time` (string) - `end_time` (string) - `bid_strategy` (string) - `bid_amount` (number) - `roas_average_floor` (number) - `optimization_goal` (string) - `billing_event` (string) - `buying_type` (string) - `rf_prediction_id` (string) - `special_ad_categories` (array of string) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, … - `creatives` (array of object; ≤ 50 items) - `optimize_card_order` (boolean): Meta carousels: false keeps your card order (max 5 cards); omit for Meta's default (true). Only with carousel_cards. - `page_id` (string) - `instagram_account_id` (string) - `identity_id` (string) - `identity_type` (string) - `organization_id` (string) - `board_id` (string) - `lead_gen_form_id` (string) - `phone_number` (string) - `campaign_type` (string; one of search, display, performance_max, demand_gen, video) - `keywords` (array of object) - `negative_keywords` (array of object) - `headlines` (array of any) - `long_headline` (string) - `descriptions` (array of any) - `business_name` (string) - `asset_group` (object) - `demand_gen` (object) - `tracking` (object) - `platform_specific_data` (object) - `validate_only` (boolean) - `post_id` (string) - `platform_post_id` (string) - `link_url` (string) - `body` (string) - `headline` (string) - `image_url` (string) - `destination` (string; required; one of messenger, instagram_direct) - `welcome_message` (object) - `workflow_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/messaging" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "destination": "messenger" }' ``` Response 200: ```json { "object": "ad_validation", "valid": true, "platform": "string", "results": [ {} ] } ``` ## Create a click-to-call ad `POST /ads/call` Access: `write` · MCP tool: `create-call-ad` · Zernio: `POST /v1/ads/call` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string; required; 1–400 characters) - `campaign_name` (string) - `ad_set_name` (string) - `ad_name` (string) - `goal` (string; one of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants) - `existing_campaign_id` (string) - `ad_set_id` (string) - `status` (string; one of active, paused) - `campaign_status` (string; one of active, paused) - `ad_set_status` (string; one of active, paused) - `ad_status` (string; one of active, paused) - `budget` (object) - `budget.amount` (number; required) - `budget.type` (string; one of daily, lifetime) - `budget_amount` (number) - `budget_type` (string; one of daily, lifetime) - `budget_level` (string; one of campaign, ad_set) - `currency` (string) - `start_time` (string) - `end_time` (string) - `bid_strategy` (string) - `bid_amount` (number) - `roas_average_floor` (number) - `optimization_goal` (string) - `billing_event` (string) - `buying_type` (string) - `rf_prediction_id` (string) - `special_ad_categories` (array of string) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, … - `creatives` (array of object; ≤ 50 items) - `optimize_card_order` (boolean): Meta carousels: false keeps your card order (max 5 cards); omit for Meta's default (true). Only with carousel_cards. - `page_id` (string) - `instagram_account_id` (string) - `identity_id` (string) - `identity_type` (string) - `organization_id` (string) - `board_id` (string) - `lead_gen_form_id` (string) - `phone_number` (string; required) - `campaign_type` (string; one of search, display, performance_max, demand_gen, video) - `keywords` (array of object) - `negative_keywords` (array of object) - `headlines` (array of any) - `long_headline` (string) - `descriptions` (array of any) - `business_name` (string) - `asset_group` (object) - `demand_gen` (object) - `tracking` (object) - `platform_specific_data` (object) - `validate_only` (boolean) - `post_id` (string) - `platform_post_id` (string) - `link_url` (string) - `body` (string) - `headline` (string) - `image_url` (string) - `call_to_action` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/call" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "phone_number": "+15551234567" }' ``` Response 200: ```json { "object": "ad_validation", "valid": true, "platform": "string", "results": [ {} ] } ``` ## Get an ad `GET /ads/{id}` With a Facebook post id (_) and ad_account_id, a placement dark post that maps to no single ad answers ad: null + dark_post; moderate its comments with the same id on /ads/{id}/comments. Access: `read` · MCP tool: `get-ad` · Zernio: `GET /v1/ads/{adId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `live` (boolean) ```bash curl "https://api.socialit.com/v1/ads/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {}, "currency": "USD", "last_synced_at": "2026-10-13T09:00:00.000Z" }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "network": "string", "campaign_id": "string", "ad_set_id": "string", "campaign_external_id": "string", "ad_set_external_id": "string", "campaign_name": "string", "ad_set_name": "string" } ``` ## Update an ad `PATCH /ads/{id}` Access: `write` · MCP tool: `update-ad` · Zernio: `PUT /v1/ads/{adId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `name` (string) - `status` (string; one of active, paused) - `budget` (object) - `budget.amount` (number; required) - `budget.type` (string; one of daily, lifetime) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, … - `headlines` (array of any; ≤ 15 items) - `descriptions` (array of any; ≤ 5 items) - `final_urls` (array of string) - `asset_group` (object) - `demand_gen` (object) - `page_id` (string) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "name": "string" }' ``` Response 200: ```json { "object": "ad", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "status": "string", "configured_status": "string", "platform_status": "string", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "currency": "USD", "bid_strategy": "string", "bid_amount": 1.5, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "is_external": true, "metrics": { "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {}, "currency": "USD", "last_synced_at": "2026-10-13T09:00:00.000Z" }, "platform_created_at": "2026-10-13T09:00:00.000Z", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "network": "string", "campaign_id": "string", "ad_set_id": "string", "campaign_external_id": "string", "ad_set_external_id": "string", "campaign_name": "string", "ad_set_name": "string", "ad_type": "string", "creative_type": "string", "goal": "string", "review_status": "string", "rejection_reason": "string", "creative": {}, "post_id": "string", "platform_post_id": "string", "targeting": {}, "daily": [ { "date": "string", "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {} } ] } ``` ## Delete an ad `DELETE /ads/{id}` Access: `write` · MCP tool: `delete-ad` · Zernio: `DELETE /v1/ads/{adId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad", "id": "string", "deleted": true, "archived": true } ``` ## Pause or resume an ad `PATCH /ads/{id}/status` Access: `write` · MCP tool: `set-ad-status` · Zernio: `PUT /v1/ads/{adId}/status` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `status` (string; required; one of active, paused) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/ID/status" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "status": "active", "platform": "string" }' ``` Response 200: ```json { "object": "ad_status_change", "level": "string", "id": "string", "external_id": "string", "platform": "string", "status": "string", "platform_status": "string", "updated": true, "skipped": true, "skipped_reasons": [ "string" ] } ``` ## Duplicate an ad `POST /ads/{id}/duplicate` Access: `write` · MCP tool: `duplicate-ad` · Zernio: `POST /v1/ads/{adId}/duplicate` ### Path parameters - `id` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `deep_copy` (boolean) - `status_option` (string; one of paused, active, inherited) - `start_time` (string) - `end_time` (string) - `rename_strategy` (string; one of none, prefix, suffix, deep_rename) - `rename_prefix` (string) - `rename_suffix` (string) - `sync_after` (boolean) - `campaign_id` (string) - `ad_set_id` (string) - `reuse_source_creative` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/ID/duplicate" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "platform": "string", "deep_copy": true }' ``` Response 201: ```json { "object": "ad_duplicate", "level": "string", "source_id": "string", "copied_external_id": "string", "copied_id": "string", "sync": "string", "raw": {} } ``` ## Get ad analytics `GET /ads/{id}/analytics` Access: `read` · MCP tool: `get-ad-analytics` · Zernio: `GET /v1/ads/{adId}/analytics` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `breakdowns` (string) ```bash curl "https://api.socialit.com/v1/ads/ID/analytics" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_analytics", "level": "string", "id": "string", "platform": "string", "name": "string", "status": "string", "currency": "USD", "budget": { "amount": 1.5, "type": "string", "level": "string", "shared_budget_id": "string" }, "from_date": "string", "to_date": "string", "backfill_pending": true, "summary": {}, "daily": [ { "date": "string", "spend": 1.5, "impressions": 1.5, "reach": 1.5, "frequency": 1.5, "clicks": 1.5, "link_clicks": 1.5, "ctr": 1.5, "cpc": 1.5, "cpm": 1.5, "engagement": 1.5, "video_views": 1.5, "conversions": 1.5, "conversion_value": 1.5, "cost_per_conversion": 1.5, "roas": 1.5, "leads": 1.5, "actions": {}, "action_values": {} } ], "breakdowns": {}, "unsupported_breakdowns": [ "string" ], "breakdown_hints": {}, "breakdown_errors": {}, "breakdown_dropped_metrics": {}, "breakdowns_range": { "from": "+15551234567", "to": "+15551234567" } } ``` ## Render previews of an ad `GET /ads/{id}/preview` Access: `read` · MCP tool: `get-ad-previews` · Zernio: `GET /v1/ads/{adId}/preview` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `formats` (string) ```bash curl "https://api.socialit.com/v1/ads/ID/preview" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_preview" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Read an ad's review verdict `GET /ads/{id}/review` Access: `read` · MCP tool: `get-ad-review` · Zernio: `GET /v1/ads/{adId}/review` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl "https://api.socialit.com/v1/ads/ID/review" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_review" } ``` ## Direct URLs of an ad's media `GET /ads/{id}/media` Access: `read` · MCP tool: `get-ad-media` · Zernio: `GET /v1/ads/{adId}/media` ### Path parameters - `id` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) ```bash curl "https://api.socialit.com/v1/ads/ID/media" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_media", "ad_id": "string", "platform": "string", "media": [ {} ] } ``` ## Render pre-create ad previews `POST /ads/preview` Access: `read` · MCP tool: `preview-ad-creative` · Zernio: `POST /v1/ads/preview` ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `formats` (array of string) - `existing_creative_id` (string) - `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, … - `creative_spec` (object) - `page_id` (string) - `instagram_account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/preview" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "formats": [ "string" ], "existing_creative_id": "string" }' ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_preview" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Creative library `GET /ads/creatives` Access: `read` · MCP tool: `list-ad-creatives` · Zernio: `GET /v1/ads/creatives` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `limit` (integer; 1–100) - `after` (string) - `fields` (string) ```bash curl "https://api.socialit.com/v1/ads/creatives" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_creative" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a standalone creative `POST /ads/creatives` Access: `write` · MCP tool: `create-ad-creative` · Zernio: `POST /v1/ads/creatives` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string) - `page_id` (string) - `instagram_account_id` (string) - `headline` (string; required) - `body` (string; required) - `description` (string) - `call_to_action` (string) - `link_url` (string; required) - `optimize_card_order` (boolean) - `image_url` (string) - `image_hash` (string) - `video` (object) - `carousel_cards` (array of object; ≤ 10 items) - `url_tags` (string) - `promotion` (object) - `creative_features` (object) - `multi_advertiser` (boolean) - `ai_disclosure` (object) ```bash curl -X POST "https://api.socialit.com/v1/ads/creatives" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "headline": "string", "body": "string", "link_url": "https://example.com" }' ``` Response 201: ```json { "object": "ad_creative" } ``` ## Creative details `GET /ads/creatives/{creativeId}` Access: `read` · MCP tool: `get-ad-creative` · Zernio: `GET /v1/ads/creatives/{creativeId}` ### Path parameters - `creativeId` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `fields` (string) - `thumbnail_width` (integer) - `thumbnail_height` (integer) ```bash curl "https://api.socialit.com/v1/ads/creatives/CREATIVE_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_creative" } ``` ## Rename a creative `PATCH /ads/creatives/{creativeId}` Access: `write` · MCP tool: `rename-ad-creative` · Zernio: `PUT /v1/ads/creatives/{creativeId}` ### Path parameters - `creativeId` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string; required; 1–400 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/creatives/CREATIVE_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string" }' ``` Response 200: ```json { "object": "ad_creative" } ``` ## Delete a creative `DELETE /ads/creatives/{creativeId}` Access: `write` · MCP tool: `delete-ad-creative` · Zernio: `DELETE /v1/ads/creatives/{creativeId}` ### Path parameters - `creativeId` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/creatives/CREATIVE_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_creative", "id": "string", "deleted": true, "archived": true } ``` ## Ad image library `GET /ads/images` Access: `read` · MCP tool: `list-ad-images` · Zernio: `GET /v1/ads/images` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `limit` (integer; 1–100) - `after` (string) - `fields` (string) ```bash curl "https://api.socialit.com/v1/ads/images" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_image" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Upload an ad image `POST /ads/images` Access: `write` · MCP tool: `upload-ad-image` · Zernio: `POST /v1/ads/images` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `image_base64` (string; ≤ 41000000 characters) - `image_url` (string) - `filename` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/images" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "image_base64": "string", "image_url": "https://example.com" }' ``` Response 201: ```json { "object": "ad_image" } ``` ## Ad video library `GET /ads/videos` Access: `read` · MCP tool: `list-ad-videos` · Zernio: `GET /v1/ads/videos` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `limit` (integer; 1–100) - `after` (string) - `fields` (string) ```bash curl "https://api.socialit.com/v1/ads/videos" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_video" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Upload an ad video `POST /ads/videos` Access: `write` · MCP tool: `upload-ad-video` · Zernio: `POST /v1/ads/videos` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `video_url` (string) - `video_base64` (string; ≤ 140000000 characters) - `filename` (string) - `title` (string) - `async` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/videos" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "video_url": "https://example.com", "video_base64": "string" }' ``` Response 201: ```json { "object": "ad_video" } ``` ## Get ad video processing status `GET /ads/videos/{videoId}` Access: `read` · MCP tool: `get-ad-video` · Zernio: `GET /v1/ads/videos/{videoId}` ### Path parameters - `videoId` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) ```bash curl "https://api.socialit.com/v1/ads/videos/VIDEO_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_video" } ``` ## Delete an ad video `DELETE /ads/videos/{videoId}` Access: `write` · MCP tool: `delete-ad-video` · Zernio: `DELETE /v1/ads/videos/{videoId}` ### Path parameters - `videoId` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/videos/VIDEO_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_video", "id": "string", "deleted": true, "archived": true } ``` ## List TikTok ad identities `GET /ads/tiktok-identities` Access: `read` · MCP tool: `list-tiktok-ad-identities` · Zernio: `GET /v1/ads/tiktok-identities` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) ```bash curl "https://api.socialit.com/v1/ads/tiktok-identities" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "tiktok_identity" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## List partnership ad content `GET /ads/partnership-content` Access: `read` · MCP tool: `list-ad-partnership-content` · Zernio: `GET /v1/ads/partnership-content` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `creator_username` (string) - `post_url` (string) - `only_allowlisted` (boolean) - `instagram_account_id` (string) ```bash curl "https://api.socialit.com/v1/ads/partnership-content" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "partnership_content" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## List partnership permissions `GET /ads/partnership-permissions` Access: `read` · MCP tool: `list-ad-partnership-permissions` · Zernio: `GET /v1/ads/partnership-permissions` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `creator_username` (string) - `instagram_account_id` (string) ```bash curl "https://api.socialit.com/v1/ads/partnership-permissions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "partnership_permission" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Set a partnership permission `POST /ads/partnership-permissions` Access: `write` · MCP tool: `set-ad-partnership-permission` · Zernio: `POST /v1/ads/partnership-permissions` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `creator_username` (string; required; 1–100 characters) - `revoke` (boolean) - `instagram_account_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/partnership-permissions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "creator_username": "string", "revoke": true }' ``` Response 200: ```json { "object": "partnership_permission" } ``` ## Flexible live insights query `GET /ads/insights` Access: `read` · MCP tool: `get-ad-insights` · Zernio: `GET /v1/ads/insights` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `object_id` (string) - `level` (string; one of account, campaign, ad_set, ad) - `fields` (string) - `breakdowns` (string) - `action_breakdowns` (string) - `action_attribution_windows` (string) - `action_report_time` (string) - `use_unified_attribution_setting` (boolean) - `filtering` (string) - `date_preset` (string) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `time_increment` (string) - `query` (string; ≤ 10000 characters) - `report_type` (string) - `data_level` (string) - `dimensions` (string) - `metrics` (string) - `page` (integer; ≥ 1) - `page_size` (integer; 1–1000) - `page_token` (string) - `limit` (integer; 1–100) - `after` (string) - `customer_id` (string) ```bash curl "https://api.socialit.com/v1/ads/insights" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_insights", "platform": "string", "ad_account_id": "string", "level": "string", "data": [ {} ], "has_more": true, "next_cursor": "string", "summary": {} } ``` ## Submit an async insights report `POST /ads/insights/reports` Access: `write` · MCP tool: `create-ad-insights-report` · Zernio: `POST /v1/ads/insights/reports` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `object_id` (string) - `level` (string; one of account, campaign, ad_set, ad) - `fields` (array of string) - `breakdowns` (array of string) - `action_breakdowns` (array of string) - `action_attribution_windows` (array of string) - `action_report_time` (string) - `use_unified_attribution_setting` (boolean) - `filtering` (array of object) - `date_preset` (string) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `time_increment` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/insights/reports" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "object_id": "string", "level": "account" }' ``` Response 201: ```json { "object": "ad_insights_report", "id": "string", "status": "string", "percent_complete": 1.5, "data": [ {} ], "has_more": true, "next_cursor": "string" } ``` ## Poll an async insights report `GET /ads/insights/reports/{reportId}` Access: `read` · MCP tool: `get-ad-insights-report` · Zernio: `GET /v1/ads/insights/reports/{reportRunId}` ### Path parameters - `reportId` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `limit` (integer; 1–100) - `after` (string) ```bash curl "https://api.socialit.com/v1/ads/insights/reports/REPORT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_insights_report", "id": "string", "status": "string", "percent_complete": 1.5, "data": [ {} ], "has_more": true, "next_cursor": "string" } ``` ## TikTok Smart+ per-creative performance `GET /ads/tiktok-smart-plus-materials` Access: `read` · MCP tool: `get-tiktok-smart-plus-materials` · Zernio: `GET /v1/ads/tiktok-smart-plus-materials` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `start_date` (string; required) - `end_date` (string; required) - `level` (string; one of ad, material) - `smart_plus_ad_ids` (string) - `ad_group_ids` (string) - `page` (integer; ≥ 1) - `page_size` (integer; 1–100) ```bash curl "https://api.socialit.com/v1/ads/tiktok-smart-plus-materials?start_date=value&end_date=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "smart_plus_material" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Google Ads search terms report `GET /ads/search-terms` Access: `read` · MCP tool: `get-ad-search-terms` · Zernio: `GET /v1/ads/search-terms` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `campaign_id` (string) - `ad_set_id` (string) - `ad_group_id` (string) - `page_token` (string) - `customer_id` (string) ```bash curl "https://api.socialit.com/v1/ads/search-terms" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "search_term" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Google Local Services Ads leads `GET /ads/local-services/leads` Access: `read` · MCP tool: `list-local-services-leads` · Zernio: `GET /v1/ads/local-services/leads` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `lead_type` (string) - `lead_status` (string) - `charged_only` (boolean) - `page_token` (string) - `customer_id` (string) ```bash curl "https://api.socialit.com/v1/ads/local-services/leads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "local_services_lead" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## List Local Services lead conversations `GET /ads/local-services/leads/{leadId}/conversations` Access: `read` · MCP tool: `list-local-services-lead-conversations` · Zernio: `GET /v1/ads/local-services/leads/{leadId}/conversations` ### Path parameters - `leadId` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `page_token` (string) - `customer_id` (string) ```bash curl "https://api.socialit.com/v1/ads/local-services/leads/LEAD_ID/conversations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "local_services_lead_conversation" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Generate keyword ideas `POST /ads/keywords/ideas` Access: `read` · MCP tool: `generate-ad-keyword-ideas` · Zernio: `POST /v1/ads/keywords/ideas` ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `customer_id` (string) - `countries` (array of string) - `language_id` (string) - `network` (string; one of GOOGLE_SEARCH, GOOGLE_SEARCH_AND_PARTNERS) - `include_adult_keywords` (boolean) - `seed_keywords` (array of string; ≤ 20 items) - `seed_url` (string) - `page_size` (integer; 1–10000) - `page_token` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/keywords/ideas" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "customer_id": "string", "countries": [ "string" ] }' ``` Response 200: ```json { "object": "list", "data": [ { "object": "keyword_idea" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Get historical keyword metrics `POST /ads/keywords/historical-metrics` Access: `read` · MCP tool: `get-ad-keyword-historical-metrics` · Zernio: `POST /v1/ads/keywords/historical-metrics` ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `customer_id` (string) - `countries` (array of string) - `language_id` (string) - `network` (string; one of GOOGLE_SEARCH, GOOGLE_SEARCH_AND_PARTNERS) - `include_adult_keywords` (boolean) - `keywords` (array of string; required; 1–10000 items) - `include_average_cpc` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/keywords/historical-metrics" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "customer_id": "string", "keywords": [ "string" ] }' ``` Response 200: ```json { "object": "list", "data": [ { "object": "keyword_idea" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## List Search keywords `GET /ads/keywords` Access: `read` · MCP tool: `list-ad-keywords` · Zernio: `GET /v1/ads/keywords` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, text) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `profile_id` (string) - `campaign_id` (string) - `ad_set_id` (string) - `status` (string; one of enabled, paused, removed) - `match_type` (string; one of exact, phrase, broad) - `negative` (boolean) - `search` (string) ```bash curl "https://api.socialit.com/v1/ads/keywords" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_keyword", "id": "string", "platform": "string", "ad_account_id": "string", "campaign_id": "string", "ad_set_id": "string", "external_id": "string", "criterion_id": "string", "text": "string", "match_type": "string", "negative": true, "status": "string", "cpc_bid": 1.5, "final_url": "https://example.com", "quality_score": 1, "metrics": {}, "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Add Search keywords `POST /ads/keywords` Access: `write` · MCP tool: `add-ad-keywords` · Zernio: `POST /v1/ads/keywords` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `ad_set_id` (string; required) - `keywords` (array of object; required; 1–200 items) - `keywords[].text` (string; required; 1–80 characters) - `keywords[].match_type` (string; one of exact, phrase, broad) - `keywords[].cpc_bid` (number) - `keywords[].final_url` (string) - `negative` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/keywords" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "ad_set_id": "string", "keywords": [ { "text": "string", "match_type": "exact" } ] }' ``` Response 201: ```json { "object": "list", "data": [ { "object": "ad_keyword", "id": "string", "platform": "string", "ad_account_id": "string", "campaign_id": "string", "ad_set_id": "string", "external_id": "string", "criterion_id": "string", "text": "string", "match_type": "string", "negative": true, "status": "string", "cpc_bid": 1.5, "final_url": "https://example.com", "quality_score": 1, "metrics": {}, "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Pause or enable a Search keyword `PATCH /ads/keywords/{id}` Access: `write` · MCP tool: `update-ad-keyword` · Zernio: `PATCH /v1/ads/keywords/{keywordId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `status` (string; required; one of enabled, paused) - `cpc_bid` (number) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/keywords/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "enabled", "cpc_bid": 0 }' ``` Response 200: ```json { "object": "ad_keyword", "id": "string", "platform": "string", "ad_account_id": "string", "campaign_id": "string", "ad_set_id": "string", "external_id": "string", "criterion_id": "string", "text": "string", "match_type": "string", "negative": true, "status": "string", "cpc_bid": 1.5, "final_url": "https://example.com", "quality_score": 1, "metrics": {}, "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Remove a Search keyword `DELETE /ads/keywords/{id}` Access: `write` · MCP tool: `delete-ad-keyword` · Zernio: `DELETE /v1/ads/keywords/{keywordId}` ### Path parameters - `id` (string; required; 1–300 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/keywords/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_keyword", "id": "string", "deleted": true, "archived": true } ``` ## List Google Ads recommendations `GET /ads/recommendations` Access: `read` · MCP tool: `list-ad-recommendations` · Zernio: `GET /v1/ads/recommendations` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `campaign_id` (string) - `types` (string) - `customer_id` (string) ```bash curl "https://api.socialit.com/v1/ads/recommendations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_recommendation" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Apply Google Ads recommendations `POST /ads/recommendations/apply` Access: `write` · MCP tool: `apply-ad-recommendations` · Zernio: `POST /v1/ads/recommendations/apply` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `recommendations` (array of object; required; 1–100 items) - `recommendations[].id` (string; required) - `recommendations[].parameters` (object) - `customer_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/recommendations/apply" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "recommendations": [ { "id": "string", "parameters": {} } ], "customer_id": "string" }' ``` Response 200: ```json { "object": "ad_recommendation_result" } ``` ## Dismiss Google Ads recommendations `POST /ads/recommendations/dismiss` Access: `write` · MCP tool: `dismiss-ad-recommendations` · Zernio: `POST /v1/ads/recommendations/dismiss` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `ids` (array of string; 1–100 items) - `resource_names` (array of string; ≤ 100 items) - `customer_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/recommendations/dismiss" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "ids": [ "string" ], "resource_names": [ "string" ] }' ``` Response 200: ```json { "object": "ad_recommendation_result" } ``` ## List portfolio bid strategies `GET /ads/bid-strategies` Access: `read` · MCP tool: `list-ad-bid-strategies` · Zernio: `GET /v1/ads/bid-strategies` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$) - `customer_id` (string) ```bash curl "https://api.socialit.com/v1/ads/bid-strategies" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "bid_strategy" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a portfolio bid strategy `POST /ads/bid-strategies` Access: `write` · MCP tool: `create-ad-bid-strategy` · Zernio: `POST /v1/ads/bid-strategies` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string; required; 1–255 characters) - `type` (string; required; one of TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE, TARGET_IMPRESSION_SHARE, TARGET_SPEND) - `target_cpa` (number) - `target_roas` (number) - `target_impression_share` (object) - `customer_id` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/bid-strategies" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "type": "TARGET_CPA" }' ``` Response 201: ```json { "object": "bid_strategy" } ``` ## Update a portfolio bid strategy `PATCH /ads/bid-strategies/{strategyId}` Access: `write` · MCP tool: `update-ad-bid-strategy` · Zernio: `PATCH /v1/ads/bid-strategies/{strategyId}` ### Path parameters - `strategyId` (string; required; 1–300 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string) - `type` (string) - `target_cpa` (number) - `target_roas` (number) - `target_impression_share` (object) - `customer_id` (string) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/bid-strategies/STRATEGY_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "type": "string" }' ``` Response 200: ```json { "object": "bid_strategy" } ``` ## List shared budgets `GET /ads/shared-budgets` Access: `read` · MCP tool: `list-ad-shared-budgets` · Zernio: `GET /v1/ads/shared-budgets` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) ```bash curl "https://api.socialit.com/v1/ads/shared-budgets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "shared_budget" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a shared budget `POST /ads/shared-budgets` Access: `write` · MCP tool: `create-ad-shared-budget` · Zernio: `POST /v1/ads/shared-budgets` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string; required; 1–255 characters) - `amount` (number; required) - `type` (string; one of daily) - `delivery_method` (string; one of standard, accelerated) ```bash curl -X POST "https://api.socialit.com/v1/ads/shared-budgets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "amount": 1.5 }' ``` Response 201: ```json { "object": "shared_budget" } ``` ## Search targeting interests `GET /ads/interests` Access: `read` · MCP tool: `search-ad-interests` · Zernio: `GET /v1/ads/interests` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `q` (string; required; 1–200 characters) - `limit` (integer; 1–100) ```bash curl "https://api.socialit.com/v1/ads/interests?q=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "targeting_option" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Search targeting options `GET /ads/targeting/search` Access: `read` · MCP tool: `search-ad-targeting` · Zernio: `GET /v1/ads/targeting/search` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `q` (string; required; 1–200 characters) - `dimension` (string) - `geo_type` (string) - `country_code` (string) - `limit` (integer; 1–100) ```bash curl "https://api.socialit.com/v1/ads/targeting/search?q=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "targeting_option" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Browse targeting categories `GET /ads/targeting/browse` Access: `read` · MCP tool: `browse-ad-targeting` · Zernio: `GET /v1/ads/targeting/browse` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `type` (string) - `parent_id` (string) - `selectable` (boolean) ```bash curl "https://api.socialit.com/v1/ads/targeting/browse" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "targeting_option" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Estimate audience reach `POST /ads/targeting/reach-estimate` Access: `read` · MCP tool: `estimate-ad-reach` · Zernio: `POST /v1/ads/targeting/reach-estimate` ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `spec` (object) - `optimization_goal` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/targeting/reach-estimate" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "targeting": {}, "spec": {} }' ``` Response 200: ```json { "object": "reach_estimate" } ``` ## Suggested bid and budget bounds `POST /ads/targeting/bid-pricing` Access: `read` · MCP tool: `get-ad-bid-pricing` · Zernio: `POST /v1/ads/targeting/bid-pricing` ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `spec` (object) - `campaign_type` (string) - `bid_type` (string; one of CPM, CPC, CPV) - `match_type` (string) - `currency` (string) - `objective_type` (string) - `optimization_target_type` (string) - `daily_budget` (number) ```bash curl -X POST "https://api.socialit.com/v1/ads/targeting/bid-pricing" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "targeting": {}, "spec": {} }' ``` Response 200: ```json { "object": "bid_pricing" } ``` ## Forecast ad delivery `POST /ads/targeting/supply-forecast` Access: `read` · MCP tool: `get-ad-supply-forecast` · Zernio: `POST /v1/ads/targeting/supply-forecast` ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `spec` (object) - `campaign_type` (string) - `time_range_start` (string; required) - `time_range_end` (string; required) - `objective_type` (string) - `optimization_target` (string) - `daily_budget` (number) - `total_budget` (number) - `currency` (string) - `competing_bid` (number) - `enable_audience_network` (boolean) - `enable_audience_expansion` (boolean) - `connected_television_only` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/targeting/supply-forecast" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "time_range_start": "string", "time_range_end": "string" }' ``` Response 200: ```json { "object": "supply_forecast" } ``` ## List custom audiences `GET /ads/audiences` Access: `read` · MCP tool: `list-ad-audiences` · Zernio: `GET /v1/ads/audiences` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at, name) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `profile_id` (string) - `type` (string) - `live` (boolean) ```bash curl "https://api.socialit.com/v1/ads/audiences" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_audience", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "description": "string", "type": "string", "subtype": "string", "status": "string", "size": 1.5, "size_lower": 1.5, "size_upper": 1.5, "spec": {}, "uploaded_count": 1, "last_uploaded_at": "2026-10-13T09:00:00.000Z", "platform_status": "string", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a custom audience `POST /ads/audiences` Access: `write` · MCP tool: `create-ad-audience` · Zernio: `POST /v1/ads/audiences` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `name` (string; required; 1–255 characters) - `description` (string; ≤ 1000 characters) - `type` (string; required; one of customer_list, website, lookalike, engagement, saved, company_list) - `customer_file_source` (string) - `retention_days` (integer; 1–540) - `rule` (object) - `pixel_id` (string) - `source_audience_id` (string) - `country` (string) - `ratio` (number; 0.01–0.2) - `engagement_source` (object) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `spec` (object) - `users` (array of object; ≤ 10000 items) - `hashed` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/audiences" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "type": "customer_list" }' ``` Response 201: ```json { "object": "ad_audience", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "description": "string", "type": "string", "subtype": "string", "status": "string", "size": 1.5, "size_lower": 1.5, "size_upper": 1.5, "spec": {}, "uploaded_count": 1, "last_uploaded_at": "2026-10-13T09:00:00.000Z", "platform_status": "string", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Get audience details `GET /ads/audiences/{id}` Access: `read` · MCP tool: `get-ad-audience` · Zernio: `GET /v1/ads/audiences/{audienceId}` ### Path parameters - `id` (string; required; 1–300 characters) ```bash curl "https://api.socialit.com/v1/ads/audiences/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_audience", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "description": "string", "type": "string", "subtype": "string", "status": "string", "size": 1.5, "size_lower": 1.5, "size_upper": 1.5, "spec": {}, "uploaded_count": 1, "last_uploaded_at": "2026-10-13T09:00:00.000Z", "platform_status": "string", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update an audience `PATCH /ads/audiences/{id}` Access: `write` · MCP tool: `update-ad-audience` · Zernio: `PUT /v1/ads/audiences/{audienceId}` ### Path parameters - `id` (string; required; 1–300 characters) ### Body - `name` (string; 1–255 characters) - `description` (string | null; ≤ 1000 characters) - `spec` (object) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/audiences/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "description": "string", "spec": {} }' ``` Response 200: ```json { "object": "ad_audience", "id": "string", "platform": "string", "ad_account_id": "string", "connection_id": "string", "profile_id": "string", "external_id": "string", "name": "string", "description": "string", "type": "string", "subtype": "string", "status": "string", "size": 1.5, "size_lower": 1.5, "size_upper": 1.5, "spec": {}, "uploaded_count": 1, "last_uploaded_at": "2026-10-13T09:00:00.000Z", "platform_status": "string", "synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Delete a custom audience `DELETE /ads/audiences/{id}` Access: `write` · MCP tool: `delete-ad-audience` · Zernio: `DELETE /v1/ads/audiences/{audienceId}` ### Path parameters - `id` (string; required; 1–300 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/audiences/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_audience", "id": "string", "deleted": true, "archived": true } ``` ## Add users to an audience `POST /ads/audiences/{id}/users` Access: `write` · MCP tool: `add-ad-audience-users` · Zernio: `POST /v1/ads/audiences/{audienceId}/users` ### Path parameters - `id` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `users` (array of object; required; 1–10000 items) - `users[].email` (string) - `users[].phone` (string) - `users[].first_name` (string) - `users[].last_name` (string) - `users[].country` (string) - `users[].zip` (string) - `users[].city` (string) - `users[].state` (string) - `users[].external_id` (string) - `users[].mobile_advertiser_id` (string) - `operation` (string; one of add, remove) - `hashed` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/audiences/ID/users" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "users": [ { "email": "you@example.com", "phone": "+15551234567" } ], "operation": "add", "hashed": true }' ``` Response 200: ```json { "object": "ad_audience_upload" } ``` ## Replace audience companies `POST /ads/audiences/{id}/companies` Access: `write` · MCP tool: `replace-ad-audience-companies` · Zernio: `POST /v1/ads/audiences/{audienceId}/companies` ### Path parameters - `id` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `companies` (array of object; required; 1–300000 items) - `companies[].company_name` (string) - `companies[].company_website` (string) - `companies[].company_email_domain` (string) - `companies[].linkedin_company_page_url` (string) - `companies[].organization_urn` (string) ```bash curl -X POST "https://api.socialit.com/v1/ads/audiences/ID/companies" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "companies": [ { "company_name": "string", "company_website": "https://example.com" } ] }' ``` Response 200: ```json { "object": "ad_audience_upload" } ``` ## Search the public Ad Library `GET /ads/library` Access: `read` · MCP tool: `search-ad-library` · Zernio: `GET /v1/ads/library` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …) - `q` (string) - `page_ids` (string) - `advertiser` (string) - `countries` (string) - `ad_type` (string) - `status` (string) - `platforms` (string) - `media_type` (string) - `languages` (string) - `since` (string) - `until` (string) - `search_type` (string) - `fields` (string) - `limit` (integer; 1–100) - `after` (string) ```bash curl "https://api.socialit.com/v1/ads/library" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_library_ad" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a reach & frequency prediction `POST /ads/rf-predictions` Access: `write` · MCP tool: `create-ad-reach-frequency-prediction` · Zernio: `POST /v1/ads/rf-predictions` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) - `budget_amount` (number) - `reach` (integer; ≥ 1) - `start_time` (string; required) - `end_time` (string; required) - `frequency_cap` (object) - `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec) - `placements` (object) - `objective` (string) - `prediction_mode` (integer) ```bash curl -X POST "https://api.socialit.com/v1/ads/rf-predictions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "start_time": "string", "end_time": "string" }' ``` Response 201: ```json { "object": "rf_prediction" } ``` ## Get a reach & frequency prediction `GET /ads/rf-predictions/{predictionId}` Access: `read` · MCP tool: `get-ad-reach-frequency-prediction` · Zernio: `GET /v1/ads/rf-predictions/{predictionId}` ### Path parameters - `predictionId` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) ```bash curl "https://api.socialit.com/v1/ads/rf-predictions/PREDICTION_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "rf_prediction" } ``` ## Cancel a reach & frequency booking `DELETE /ads/rf-predictions/{predictionId}` Access: `write` · MCP tool: `cancel-ad-reach-frequency-prediction` · Zernio: `DELETE /v1/ads/rf-predictions/{predictionId}` ### Path parameters - `predictionId` (string; required; 1–300 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/rf-predictions/PREDICTION_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "rf_prediction", "id": "string", "deleted": true, "archived": true } ``` ## Reserve reach & frequency inventory `POST /ads/rf-predictions/{predictionId}/reserve` Access: `write` · MCP tool: `reserve-ad-reach-frequency-prediction` · Zernio: `POST /v1/ads/rf-predictions/{predictionId}/reserve` ### Path parameters - `predictionId` (string; required; 1–300 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts - `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…) ```bash curl -X POST "https://api.socialit.com/v1/ads/rf-predictions/PREDICTION_ID/reserve" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string" }' ``` Response 200: ```json { "object": "rf_prediction" } ``` --- Source: https://socialit.com/docs/api-reference/ads/ # Ads: accounts & measurement API > Ad accounts, account-level ad management, tracking tags, lead gen, product catalogs and conversions. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## Update an ads connection `PATCH /ads/connections/{connectionId}` Changes the local label of an ads connection or moves it (and its ad accounts) to another profile. Access: `write` · MCP tool: `update-ad-connection` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) ### Body - `name` (string | null; ≤ 100 characters) - `profile_id` (string | null; ≤ 80 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "profile_id": "string" }' ``` Response 200: ```json { "object": "ad_connection", "id": "string", "platform": "string", "connect_flow": "string", "profile_id": "string", "social_account_id": "string", "external_user_id": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "status": "active", "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "metadata": {}, "ad_account_count": 1, "sync": { "status": "string", "error": "string", "last_synced_at": "2026-10-13T09:00:00.000Z", "initial_sync_completed_at": "2026-10-13T09:00:00.000Z" }, "last_discovered_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Re-discover ad accounts `POST /ads/connections/{connectionId}/discover` Lists the ad accounts the connection reaches on the network now: new ones are added (selected), vanished ones become closed. Access: `write` · MCP tool: `discover-ad-connection-accounts` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) ```bash curl -X POST "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/discover" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_account", "id": "string", "connection_id": "string", "profile_id": "string", "platform": "string", "external_id": "string", "name": "string", "currency": "USD", "timezone": "Europe/Prague", "status": "string", "platform_status": "string", "business_id": "string", "business_name": "string", "manager_customer_id": "string", "is_manager": true, "is_test": true, "selected": true, "selectable": true, "unusable_reason": "string", "billing_status": "string", "metadata": {}, "last_discovered_at": "2026-10-13T09:00:00.000Z", "last_synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## List business portfolios `GET /ads/connections/{connectionId}/businesses` Meta business portfolios the connected user belongs to, with their verification status. Access: `read` · MCP tool: `list-ad-businesses` · Zernio: `GET /v1/ads/businesses` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) ### Query parameters - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/businesses" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "business", "id": "string", "name": "string", "verification_status": "string", "created_at": "2026-10-13T09:00:00.000Z", "permitted_tasks": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## List business users `GET /ads/connections/{connectionId}/businesses/{businessId}/users` People and system users of a Meta business portfolio (the ids to assign to Pages, ad accounts and pixels). Access: `read` · MCP tool: `list-ad-business-users` · Zernio: `GET /v1/ads/businesses/users` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) - `businessId` (string; required; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/businesses/BUSINESS_ID/users" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "business_user", "id": "string", "name": "string", "email": "you@example.com", "role": "string", "type": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## List TikTok Business Centers `GET /ads/connections/{connectionId}/business-centers` The TikTok Business Centers the connection can read, with their advertiser counts. Access: `read` · MCP tool: `list-ad-business-centers` · Zernio: `GET /v1/ads/business-centers` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) ```bash curl "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/business-centers" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "business_center", "id": "string", "name": "string", "advertiser_count": 1, "role": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## List Page users `GET /ads/connections/{connectionId}/pages/{pageId}/users` People of a business portfolio assigned to a Facebook Page. Access: `read` · MCP tool: `list-ad-page-users` · Zernio: `GET /v1/ads/page-users` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) - `pageId` (string; required; 1–256 characters) ### Query parameters - `business_id` (string; required; 1–64 characters) ```bash curl "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pages/PAGE_ID/users?business_id=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "page_user", "id": "string", "page_id": "string", "name": "string", "tasks": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Assign a user to a Page `POST /ads/connections/{connectionId}/pages/{pageId}/users` Gives a business user tasks on a Facebook Page (replaces their task set). ADVERTISE is what ad creation needs. Access: `admin` · MCP tool: `assign-ad-page-user` · Zernio: `POST /v1/ads/page-users` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) - `pageId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `business_id` (string; required; 1–64 characters) - `user_id` (string; required; 1–64 characters) - `tasks` (array of string; required; ≥ 1 items) ```bash curl -X POST "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pages/PAGE_ID/users" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "business_id": "string", "user_id": "string", "tasks": [ "MANAGE" ] }' ``` Response 201: ```json { "object": "page_user", "id": "string", "page_id": "string", "name": "string", "tasks": [ "string" ] } ``` ## Remove a user from a Page `DELETE /ads/connections/{connectionId}/pages/{pageId}/users/{userId}` Access: `admin` · MCP tool: `remove-ad-page-user` · Zernio: `DELETE /v1/ads/page-users` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) - `pageId` (string; required; 1–256 characters) - `userId` (string; required; 1–256 characters) ### Query parameters - `business_id` (string; 1–64 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pages/PAGE_ID/users/USER_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "page_user", "id": "string", "deleted": true } ``` ## Get the Google Ads manager hierarchy `GET /ads/connections/{connectionId}/hierarchy` Live manager (MCC) and client tree of a Google Ads connection, with pending invitations and link status. Access: `read` · MCP tool: `get-ad-manager-hierarchy` · Zernio: `GET /v1/ads/accounts/hierarchy` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) ```bash curl "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/hierarchy" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "manager_hierarchy", "connection_id": "string", "roots": [ { "customer_id": "string", "name": "string", "currency": "USD", "time_zone": "string", "manager": true, "test_account": true, "status": "string", "manager_links": [ { "manager_customer_id": "string", "manager_link_id": "string", "status": "string" } ], "clients": [ { "customer_id": "string", "name": "string", "currency": "USD", "time_zone": "string", "manager": true, "test_account": true } ] } ], "direct_customers": [ { "customer_id": "string", "manager": true, "pending_invitations": [ { "manager_customer_id": "string", "manager_link_id": "string" } ] } ], "unavailable": [ { "customer_id": "string", "reason": "string" } ], "truncated": true } ``` ## Invite a client account to a manager `POST /ads/connections/{connectionId}/manager-links` Sends a manager-to-client link invitation (Google Ads). The link stays PENDING until the client accepts. Access: `admin` · MCP tool: `create-ad-manager-link` · Zernio: `POST /v1/ads/accounts/manager-links` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `manager_customer_id` (string; required; 1–20 characters) - `client_customer_id` (string; required; 1–20 characters) - `validate_only` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/manager-links" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "manager_customer_id": "string", "client_customer_id": "string", "validate_only": true }' ``` Response 201: ```json { "object": "manager_link", "manager_customer_id": "string", "client_customer_id": "string", "manager_link_id": "string", "status": "string", "validate_only": true } ``` ## Accept, decline, cancel or end a manager link `PATCH /ads/connections/{connectionId}/manager-links/{managerLinkId}` Access: `admin` · MCP tool: `update-ad-manager-link` · Zernio: `PATCH /v1/ads/accounts/manager-links` ### Path parameters - `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…) - `managerLinkId` (string; required; 1–256 characters) ### Body - `manager_customer_id` (string; required; 1–20 characters) - `client_customer_id` (string; required; 1–20 characters) - `action` (string; required; one of accept, decline, cancel, unlink) - `validate_only` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/manager-links/MANAGER_LINK_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "manager_customer_id": "string", "client_customer_id": "string", "action": "accept", "validate_only": true }' ``` Response 200: ```json { "object": "manager_link", "manager_customer_id": "string", "client_customer_id": "string", "manager_link_id": "string", "status": "string", "validate_only": true } ``` ## List ad accounts `GET /ads/accounts` The platform ad accounts reached by the workspace ads connections. refresh=true re-discovers the matching connections live first. Access: `read` · MCP tool: `list-ad-accounts` · Zernio: `GET /v1/ads/accounts` ### Query parameters - `page` (integer; ≥ 1) - `limit` (integer; 1–100) - `connection_id` (string; 1–80 characters) - `platform` (string; 1–40 characters) - `profile_id` (string; 1–80 characters) - `status` (string; one of active, pending, disabled, closed, unknown) - `selected` (boolean) - `external_id` (string; 1–256 characters) - `search` (string; 1–200 characters) - `refresh` (boolean) - `in_scope_only` (boolean) - `sort` (string; one of name, created_at, platform, status) - `order` (string; one of asc, desc) ```bash curl "https://api.socialit.com/v1/ads/accounts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_account", "id": "string", "connection_id": "string", "profile_id": "string", "platform": "string", "external_id": "string", "name": "string", "currency": "USD", "timezone": "Europe/Prague", "status": "string", "platform_status": "string", "business_id": "string", "business_name": "string", "manager_customer_id": "string", "is_manager": true, "is_test": true, "selected": true, "selectable": true, "unusable_reason": "string", "billing_status": "string", "metadata": {}, "last_discovered_at": "2026-10-13T09:00:00.000Z", "last_synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a Meta ad account `POST /ads/accounts` Creates an ad account in a Meta business portfolio (a payment method must then be added in Ads Manager). Access: `admin` · MCP tool: `create-ad-account` · Zernio: `POST /v1/ads/accounts` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `connection_id` (string; required; 1–80 characters) - `business_id` (string; required; 1–64 characters) - `name` (string; required; 1–100 characters) - `currency` (string; required; pattern ^[A-Za-z]{3}$) - `timezone_id` (integer; required) - `end_advertiser` (string; 1–64 characters) - `media_agency` (string; 1–64 characters) - `partner` (string; 1–64 characters) - `invoice` (boolean) - `invoice_group_id` (string; 1–64 characters) - `invoicing_emails` (array of string (email); ≤ 20 items) - `io` (boolean) - `po_number` (string; 1–64 characters) - `funding_id` (string; 1–64 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "string", "business_id": "string", "name": "string", "currency": "USD", "timezone_id": 0 }' ``` Response 201: ```json { "object": "ad_account", "id": "string", "connection_id": "string", "profile_id": "string", "platform": "string", "external_id": "string", "name": "string", "currency": "USD", "timezone": "Europe/Prague", "status": "string", "platform_status": "string", "business_id": "string", "business_name": "string", "manager_customer_id": "string", "is_manager": true, "is_test": true, "selected": true, "selectable": true, "unusable_reason": "string", "billing_status": "string", "metadata": {}, "last_discovered_at": "2026-10-13T09:00:00.000Z", "last_synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "payment_method_required": true, "ads_manager_url": "https://example.com", "next_steps": "string", "warnings": [ "string" ] } ``` ## Get an ad account `GET /ads/accounts/{adAccountId}` Access: `read` · MCP tool: `get-ad-account` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_account", "id": "string", "connection_id": "string", "profile_id": "string", "platform": "string", "external_id": "string", "name": "string", "currency": "USD", "timezone": "Europe/Prague", "status": "string", "platform_status": "string", "business_id": "string", "business_name": "string", "manager_customer_id": "string", "is_manager": true, "is_test": true, "selected": true, "selectable": true, "unusable_reason": "string", "billing_status": "string", "metadata": {}, "last_discovered_at": "2026-10-13T09:00:00.000Z", "last_synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Select or move an ad account `PATCH /ads/accounts/{adAccountId}` Local settings: selected (managed, synced, billed) and profile_id. Access: `write` · MCP tool: `update-ad-account` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Body - `selected` (boolean) - `profile_id` (string | null; ≤ 80 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "selected": true, "profile_id": "string" }' ``` Response 200: ```json { "object": "ad_account", "id": "string", "connection_id": "string", "profile_id": "string", "platform": "string", "external_id": "string", "name": "string", "currency": "USD", "timezone": "Europe/Prague", "status": "string", "platform_status": "string", "business_id": "string", "business_name": "string", "manager_customer_id": "string", "is_manager": true, "is_test": true, "selected": true, "selectable": true, "unusable_reason": "string", "billing_status": "string", "metadata": {}, "last_discovered_at": "2026-10-13T09:00:00.000Z", "last_synced_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update ad account settings on the network `PATCH /ads/accounts/{adAccountId}/settings` Meta: name, spend cap, amount-spent reset, default DSA beneficiary / payor. Google: account tracking template and final URL suffix. Access: `write` · MCP tool: `update-ad-account-settings` · Zernio: `PATCH /v1/ads/accounts` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Body - `name` (string; 1–100 characters) - `spend_cap` (number | null) - `reset_amount_spent` (boolean) - `default_dsa_beneficiary` (string; 1–512 characters) - `default_dsa_payor` (string; 1–512 characters) - `tracking_url_template` (string; ≤ 2048 characters) - `final_url_suffix` (string; ≤ 2048 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/settings" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "spend_cap": 0, "reset_amount_spent": true, "default_dsa_beneficiary": "string", "default_dsa_payor": "string" }' ``` Response 200: ```json { "object": "ad_account_settings", "ad_account_id": "string", "platform": "string", "name": "string", "spend_cap": 1.5, "url_tracking": { "tracking_url_template": "string", "final_url_suffix": "string" }, "dsa_defaults": { "beneficiary": "string", "payor": "string" }, "finance": { "object": "ad_account_finance", "ad_account_id": "string", "currency": "USD", "balance": 1.5, "amount_spent": 1.5, "spend_cap": 1.5, "funding_source": { "display_string": "string", "type": 1.5 } } } ``` ## Get ad account finances `GET /ads/accounts/{adAccountId}/finance` Balance, total spend, spend cap and funding source (Meta). Access: `read` · MCP tool: `get-ad-account-finance` · Zernio: `GET /v1/ads/accounts/finance` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/finance" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_account_finance", "ad_account_id": "string", "currency": "USD", "balance": 1.5, "amount_spent": 1.5, "spend_cap": 1.5, "funding_source": { "display_string": "string", "type": 1.5 } } ``` ## Read campaigns and ad sets live `GET /ads/accounts/{adAccountId}/live` Reads campaigns and ad sets straight from the network (Meta, TikTok), e.g. to check budgets before a write. Access: `read` · MCP tool: `get-ad-account-live` · Zernio: `GET /v1/ads/accounts/live` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `status` (string; 1–200 characters) - `level` (string; one of campaign, ad_set) - `limit` (integer; 1–200) - `campaigns_cursor` (string; 1–4096 characters) - `ad_sets_cursor` (string; 1–4096 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/live" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_account_live", "ad_account_id": "string", "platform": "string", "currency": "USD", "read_at": "2026-10-13T09:00:00.000Z", "campaigns": [ { "id": "string", "name": "string", "status": "string", "platform_status": "string", "configured_status": "string", "budget": { "amount": 1.5, "type": "string" }, "daily_budget": 1.5, "lifetime_budget": 1.5, "budget_remaining": 1.5, "bid_strategy": "string", "spend_cap": 1.5 } ], "ad_sets": [ { "id": "string", "name": "string", "status": "string", "platform_status": "string", "configured_status": "string", "budget": { "amount": 1.5, "type": "string" }, "daily_budget": 1.5, "lifetime_budget": 1.5, "budget_remaining": 1.5, "bid_strategy": "string", "campaign_id": "string", "bid_amount": 1.5, "optimization_goal": "string", "billing_event": "string", "promoted_object": {}, "targeting": {}, "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z" } ], "next_cursors": { "campaigns": "string", "ad_sets": "string" } } ``` ## Get DSA defaults `GET /ads/accounts/{adAccountId}/dsa-defaults` Access: `read` · MCP tool: `get-ad-account-dsa-defaults` · Zernio: `GET /v1/ads/dsa-defaults` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/dsa-defaults" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "dsa_defaults", "ad_account_id": "string", "beneficiary": "string", "payor": "string" } ``` ## Get DSA recommendations `GET /ads/accounts/{adAccountId}/dsa-recommendations` Suggested beneficiary / payor names for EU DSA disclosures (never applied automatically). Access: `read` · MCP tool: `get-ad-account-dsa-recommendations` · Zernio: `GET /v1/ads/dsa-recommendations` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/dsa-recommendations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "dsa_recommendations", "ad_account_id": "string", "recommendations": [ "string" ] } ``` ## List ad account users `GET /ads/accounts/{adAccountId}/users` Access: `read` · MCP tool: `list-ad-account-users` · Zernio: `GET /v1/ads/accounts/users` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `business_id` (string; 1–64 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/users" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_account_user", "id": "string", "name": "string", "email": "you@example.com", "role": "string", "tasks": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Assign a user to an ad account `POST /ads/accounts/{adAccountId}/users` MANAGE = admin, ADVERTISE creates ads, ANALYZE reads reports, DRAFT edits drafts. Replaces the user’s task set. Access: `admin` · MCP tool: `assign-ad-account-user` · Zernio: `POST /v1/ads/accounts/users` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `user_id` (string; required; 1–64 characters) - `tasks` (array of string; required; ≥ 1 items) - `business_id` (string; 1–64 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/users" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "user_id": "string", "tasks": [ "MANAGE" ], "business_id": "string" }' ``` Response 201: ```json { "object": "ad_account_user", "id": "string", "name": "string", "email": "you@example.com", "role": "string", "tasks": [ "string" ] } ``` ## Remove a user from an ad account `DELETE /ads/accounts/{adAccountId}/users/{userId}` Access: `admin` · MCP tool: `remove-ad-account-user` · Zernio: `DELETE /v1/ads/accounts/users` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `userId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/users/USER_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_account_user", "id": "string", "deleted": true } ``` ## Ad account change log `GET /ads/accounts/{adAccountId}/activity` Who changed what and when (Meta activities, Google change history: last 30 days). Access: `read` · MCP tool: `list-ad-account-activity` · Zernio: `GET /v1/ads/activity` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `since` (string; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD - `until` (string; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD - `object_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/activity" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_activity", "id": "string", "event_type": "string", "event_time": "2026-10-13T09:00:00.000Z", "actor_id": "string", "actor_name": "string", "object_type": "string", "object_id": "string", "object_name": "string", "application_name": "string", "translated_event_type": "string", "extra_data": {} } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## List A/B tests and lift studies `GET /ads/accounts/{adAccountId}/studies` Access: `read` · MCP tool: `list-ad-studies` · Zernio: `GET /v1/ads/studies` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `fields` (string; 1–2000 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/studies" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_study", "id": "string", "name": "string", "type": "string", "description": "string", "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "cells": [ {} ], "raw": {} } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## List Instagram ad identities `GET /ads/accounts/{adAccountId}/instagram-accounts` Access: `read` · MCP tool: `list-ad-instagram-accounts` · Zernio: `GET /v1/ads/instagram-accounts` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram-accounts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "instagram_identities", "ad_account_id": "string", "accounts": [ { "ig_user_id": "string", "username": "string", "profile_picture_url": "https://example.com", "is_page_backed": true, "source": "string" } ], "pages": [ { "page_id": "string", "name": "string", "instagram_business_account": { "ig_user_id": "string", "username": "string", "profile_picture_url": "https://example.com" }, "connected_instagram_account": { "ig_user_id": "string", "username": "string", "profile_picture_url": "https://example.com" } } ], "resolved": { "page_id": "string", "ig_user_id": "string", "source": "string" } } ``` ## List Instagram posts to boost `GET /ads/accounts/{adAccountId}/instagram-posts` Access: `read` · MCP tool: `list-ad-instagram-posts` · Zernio: `GET /v1/ads/instagram-posts` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `ig_user_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram-posts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "instagram_post", "id": "string", "caption": "string", "media_type": "string", "media_url": "https://example.com", "thumbnail_url": "https://example.com", "permalink": "string", "timestamp": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string", "ig_user_id": "string", "username": "string" } ``` ## List advertisable apps `GET /ads/accounts/{adAccountId}/advertisable-applications` Access: `read` · MCP tool: `list-advertisable-applications` · Zernio: `GET /v1/ads/advertisable-applications` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/advertisable-applications" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "advertisable_application", "id": "string", "name": "string", "supported_platforms": [ "string" ], "store_urls": {} } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Get iOS 14 campaign limits `GET /ads/accounts/{adAccountId}/ios-campaign-limits` Access: `read` · MCP tool: `get-ios-campaign-limits` · Zernio: `GET /v1/ads/ios-fourteen-campaign-limits` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `application_id` (string; required; 1–64 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/ios-campaign-limits?application_id=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ios_campaign_limits", "application_id": "string", "campaign_group_limit": 1.5, "campaign_limit": 1.5, "details": [ {} ] } ``` ## List TikTok pixels `GET /ads/accounts/{adAccountId}/pixels` TikTok pixels with their supported optimization events. Access: `read` · MCP tool: `list-ad-pixels` · Zernio: `GET /v1/ads/pixels` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `code` (string; 1–64 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pixels" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_pixel", "id": "string", "code": "string", "name": "string", "events": [ "string" ], "event_details": [ { "name": "string", "optimization_event": "string", "custom": true } ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## List custom conversions `GET /ads/accounts/{adAccountId}/custom-conversions` Meta custom conversions of the ad account, archived included. Access: `read` · MCP tool: `list-custom-conversions` · Zernio: `GET /v1/accounts/{accountId}/custom-conversions` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "custom_conversion", "id": "string", "name": "string", "rule": {}, "custom_event_type": "string", "pixel_id": "string", "is_archived": true, "default_conversion_value": 1.5, "reused": true } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a custom conversion `POST /ads/accounts/{adAccountId}/custom-conversions` Creates a Meta custom conversion, or returns the existing non-archived one with the same name on the same pixel (reused: true, 200). Access: `write` · MCP tool: `create-custom-conversion` · Zernio: `POST /v1/accounts/{accountId}/custom-conversions` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–100 characters) - `pixel_id` (string; required; 1–64 characters) - `custom_event_type` (string; required; 1–64 characters) - `rule` (object; required) - `default_conversion_value` (number) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "pixel_id": "string", "custom_event_type": "string", "rule": {}, "default_conversion_value": 1.5 }' ``` Response 200: ```json { "object": "custom_conversion", "id": "string", "name": "string", "rule": {}, "custom_event_type": "string", "pixel_id": "string", "is_archived": true, "default_conversion_value": 1.5, "reused": true } ``` ## List ad labels `GET /ads/accounts/{adAccountId}/labels` Access: `read` · MCP tool: `list-ad-labels` · Zernio: `GET /v1/ads/labels` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_label", "id": "string", "name": "string", "status": "string", "background_color": "string", "description": "string", "resource_name": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create an ad label `POST /ads/accounts/{adAccountId}/labels` Access: `write` · MCP tool: `create-ad-label` · Zernio: `POST /v1/ads/labels` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–80 characters) - `background_color` (string; pattern ^#[0-9A-Fa-f]{6}$) - `description` (string; 1–200 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "background_color": "string", "description": "string" }' ``` Response 201: ```json { "object": "ad_label", "id": "string", "name": "string", "status": "string", "background_color": "string", "description": "string", "resource_name": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update an ad label `PATCH /ads/accounts/{adAccountId}/labels/{labelId}` Access: `write` · MCP tool: `update-ad-label` · Zernio: `PATCH /v1/ads/labels/{labelId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `labelId` (string; required; 1–256 characters) ### Body - `name` (string; 1–80 characters) - `background_color` (string; pattern ^#[0-9A-Fa-f]{6}$) - `description` (string; 1–200 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels/LABEL_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "background_color": "string", "description": "string" }' ``` Response 200: ```json { "object": "ad_label", "id": "string", "name": "string", "status": "string", "background_color": "string", "description": "string", "resource_name": "string", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Remove an ad label `DELETE /ads/accounts/{adAccountId}/labels/{labelId}` Access: `write` · MCP tool: `delete-ad-label` · Zernio: `DELETE /v1/ads/labels/{labelId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `labelId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels/LABEL_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_label", "id": "string", "deleted": true } ``` ## Attach a label `POST /ads/accounts/{adAccountId}/labels/{labelId}/assignments` Attaches a Google Ads label to campaigns, ad groups, ads and keywords; targets that already carry it count as unchanged. Access: `write` · MCP tool: `attach-ad-label` · Zernio: `POST /v1/ads/labels/{labelId}/assignments` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `labelId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `campaign_ids` (array of string; ≤ 1000 items) - `ad_set_ids` (array of string; ≤ 1000 items) - `ad_ids` (array of string; ≤ 1000 items) - `keyword_ids` (array of string; ≤ 1000 items) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels/LABEL_ID/assignments" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "campaign_ids": [ "string" ], "ad_set_ids": [ "string" ], "ad_ids": [ "string" ], "keyword_ids": [ "string" ] }' ``` Response 200: ```json { "object": "label_assignment_result", "label_id": "string", "attached": 1, "detached": 1, "unchanged": 1 } ``` ## Detach a label `DELETE /ads/accounts/{adAccountId}/labels/{labelId}/assignments` Access: `write` · MCP tool: `detach-ad-label` · Zernio: `DELETE /v1/ads/labels/{labelId}/assignments` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `labelId` (string; required; 1–256 characters) ### Query parameters - `campaign_ids` (string; ≤ 10000 characters): Comma separated ids - `ad_set_ids` (string; ≤ 10000 characters): Comma separated ids - `ad_ids` (string; ≤ 10000 characters): Comma separated ids - `keyword_ids` (string; ≤ 10000 characters): Comma separated ids ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels/LABEL_ID/assignments" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "label_assignment_result", "label_id": "string", "attached": 1, "detached": 1, "unchanged": 1 } ``` ## List high-demand periods `GET /ads/accounts/{adAccountId}/high-demand-periods` Scheduled budget increases on a Meta campaign or ad set (exactly one of campaign_id / ad_set_id). Access: `read` · MCP tool: `list-high-demand-periods` · Zernio: `GET /v1/ads/high-demand-periods` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `campaign_id` (string; 1–64 characters) - `ad_set_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/high-demand-periods" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "high_demand_period", "id": "string", "target_id": "string", "budget_value": 1.5, "budget_value_type": "string", "time_start": "2026-10-13T09:00:00.000Z", "time_end": "2026-10-13T09:00:00.000Z", "recurrence_type": "string", "raw": {} } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Schedule a budget increase `POST /ads/accounts/{adAccountId}/high-demand-periods` Access: `write` · MCP tool: `create-high-demand-period` · Zernio: `POST /v1/ads/high-demand-periods` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `campaign_id` (string; 1–64 characters) - `ad_set_id` (string; 1–64 characters) - `budget_value` (number; required) - `budget_value_type` (string; required; one of ABSOLUTE, MULTIPLIER) - `time_start` (string | integer; required): ISO 8601 date-time or unix seconds - `time_end` (string | integer; required): ISO 8601 date-time or unix seconds - `recurrence_type` (string; one of ONE_TIME, WEEKLY, MONTHLY) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/high-demand-periods" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "campaign_id": "string", "budget_value": 1.5, "budget_value_type": "ABSOLUTE", "time_start": "string", "time_end": "string" }' ``` Response 201: ```json { "object": "high_demand_period", "id": "string", "target_id": "string", "budget_value": 1.5, "budget_value_type": "string", "time_start": "2026-10-13T09:00:00.000Z", "time_end": "2026-10-13T09:00:00.000Z", "recurrence_type": "string", "raw": {} } ``` ## List value rule sets `GET /ads/accounts/{adAccountId}/value-rule-sets` Access: `read` · MCP tool: `list-value-rule-sets` · Zernio: `GET /v1/ads/value-rule-sets` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/value-rule-sets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "value_rule_set", "id": "string", "name": "string", "rules": [ { "id": "string", "name": "string", "adjust_sign": "string", "adjust_value": 1.5, "status": "string", "criteria": [] } ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a value rule set `POST /ads/accounts/{adAccountId}/value-rule-sets` Access: `write` · MCP tool: `create-value-rule-set` · Zernio: `POST /v1/ads/value-rule-sets` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–100 characters) - `rules` (array of object; required; 1–50 items) - `rules[].id` (string | null; ≤ 64 characters) - `rules[].name` (string; required; 1–100 characters) - `rules[].adjust_sign` (string; required; one of INCREASE, DECREASE) - `rules[].adjust_value` (integer; required; 1–1000) - `rules[].status` (string; 1–32 characters) - `rules[].criteria` (array of object; required; ≥ 1 items) - `rules[].criteria[].id` (string | null; ≤ 64 characters) - `rules[].criteria[].criteria_type` (string; required; one of AGE, GENDER, OS_TYPE, DEVICE_PLATFORM, LOCATION, PLACEMENT, OMNI_CHANNEL, AUDIENCE_LABEL) - `rules[].criteria[].operator` (string; one of CONTAINS) - `rules[].criteria[].criteria_values` (array of string; required; ≥ 1 items) - `rules[].criteria[].criteria_value_types` (array of string) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/value-rule-sets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "rules": [ { "name": "string", "adjust_sign": "INCREASE", "adjust_value": 1, "criteria": [ { "criteria_type": "AGE", "criteria_values": [] } ] } ] }' ``` Response 201: ```json { "object": "value_rule_set", "id": "string", "name": "string", "rules": [ { "id": "string", "name": "string", "adjust_sign": "string", "adjust_value": 1.5, "status": "string", "criteria": [ { "id": "string", "criteria_type": "string", "operator": "string", "criteria_values": [], "criteria_value_types": [] } ] } ] } ``` ## Read a value rule set `GET /ads/accounts/{adAccountId}/value-rule-sets/{valueRuleSetId}` Access: `read` · MCP tool: `get-value-rule-set` · Zernio: `GET /v1/ads/value-rule-sets/{valueRuleSetId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `valueRuleSetId` (string; required; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/value-rule-sets/VALUE_RULE_SET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "value_rule_set", "id": "string", "name": "string", "rules": [ { "id": "string", "name": "string", "adjust_sign": "string", "adjust_value": 1.5, "status": "string", "criteria": [ { "id": "string", "criteria_type": "string", "operator": "string", "criteria_values": [], "criteria_value_types": [] } ] } ] } ``` ## Replace a value rule set `PATCH /ads/accounts/{adAccountId}/value-rule-sets/{valueRuleSetId}` Full replace: keep a rule or criterion by echoing its id, omit it to delete it. Access: `write` · MCP tool: `replace-value-rule-set` · Zernio: `PUT /v1/ads/value-rule-sets/{valueRuleSetId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `valueRuleSetId` (string; required; 1–256 characters) ### Body - `name` (string; required; 1–100 characters) - `rules` (array of object; required; 1–50 items) - `rules[].id` (string | null; ≤ 64 characters) - `rules[].name` (string; required; 1–100 characters) - `rules[].adjust_sign` (string; required; one of INCREASE, DECREASE) - `rules[].adjust_value` (integer; required; 1–1000) - `rules[].status` (string; 1–32 characters) - `rules[].criteria` (array of object; required; ≥ 1 items) - `rules[].criteria[].id` (string | null; ≤ 64 characters) - `rules[].criteria[].criteria_type` (string; required; one of AGE, GENDER, OS_TYPE, DEVICE_PLATFORM, LOCATION, PLACEMENT, OMNI_CHANNEL, AUDIENCE_LABEL) - `rules[].criteria[].operator` (string; one of CONTAINS) - `rules[].criteria[].criteria_values` (array of string; required; ≥ 1 items) - `rules[].criteria[].criteria_value_types` (array of string) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/value-rule-sets/VALUE_RULE_SET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "rules": [ { "name": "string", "adjust_sign": "INCREASE", "adjust_value": 1, "criteria": [ { "criteria_type": "AGE", "criteria_values": [] } ] } ] }' ``` Response 200: ```json { "object": "value_rule_set", "id": "string", "name": "string", "rules": [ { "id": "string", "name": "string", "adjust_sign": "string", "adjust_value": 1.5, "status": "string", "criteria": [ { "id": "string", "criteria_type": "string", "operator": "string", "criteria_values": [], "criteria_value_types": [] } ] } ] } ``` ## Delete a value rule set `DELETE /ads/accounts/{adAccountId}/value-rule-sets/{valueRuleSetId}` Access: `write` · MCP tool: `delete-value-rule-set` · Zernio: `DELETE /v1/ads/value-rule-sets/{valueRuleSetId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `valueRuleSetId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/value-rule-sets/VALUE_RULE_SET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "value_rule_set", "id": "string", "deleted": true } ``` ## List negative keyword lists `GET /ads/accounts/{adAccountId}/negative-keyword-lists` Google Ads shared negative keyword lists. Access: `read` · MCP tool: `list-negative-keyword-lists` · Zernio: `GET /v1/ads/accounts/negative-keyword-lists` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "negative_keyword_list", "id": "string", "resource_name": "string", "name": "string", "member_count": 1, "reference_count": 1, "keywords": [ { "criterion_id": "string", "text": "string", "match_type": "string" } ], "created": 1, "removed": 1 } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a negative keyword list `POST /ads/accounts/{adAccountId}/negative-keyword-lists` Access: `write` · MCP tool: `create-negative-keyword-list` · Zernio: `POST /v1/ads/accounts/negative-keyword-lists` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–255 characters) - `keywords` (array of string | object; ≤ 5000 items) - one of: Option 1 (string) - one of: Option 2 (object) - `keywords.text` (string; required; 1–80 characters) - `keywords.match_type` (string; one of exact, phrase, broad) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "keywords": [ "string" ] }' ``` Response 201: ```json { "object": "negative_keyword_list", "id": "string", "resource_name": "string", "name": "string", "member_count": 1, "reference_count": 1, "keywords": [ { "criterion_id": "string", "text": "string", "match_type": "string" } ], "created": 1, "removed": 1 } ``` ## Get a negative keyword list `GET /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}` Access: `read` · MCP tool: `get-negative-keyword-list` · Zernio: `GET /v1/ads/accounts/negative-keyword-lists/{listId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `listId` (string; required; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists/LIST_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "negative_keyword_list", "id": "string", "resource_name": "string", "name": "string", "member_count": 1, "reference_count": 1, "keywords": [ { "criterion_id": "string", "text": "string", "match_type": "string" } ], "created": 1, "removed": 1 } ``` ## Rename a negative keyword list `PATCH /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}` Access: `write` · MCP tool: `rename-negative-keyword-list` · Zernio: `PUT /v1/ads/accounts/negative-keyword-lists/{listId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `listId` (string; required; 1–256 characters) ### Body - `name` (string; required; 1–255 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists/LIST_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }' ``` Response 200: ```json { "object": "negative_keyword_list", "id": "string", "resource_name": "string", "name": "string", "member_count": 1, "reference_count": 1, "keywords": [ { "criterion_id": "string", "text": "string", "match_type": "string" } ], "created": 1, "removed": 1 } ``` ## Delete a negative keyword list `DELETE /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}` Access: `write` · MCP tool: `delete-negative-keyword-list` · Zernio: `DELETE /v1/ads/accounts/negative-keyword-lists/{listId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `listId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists/LIST_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "negative_keyword_list", "id": "string", "deleted": true } ``` ## Replace negative list keywords `PATCH /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}/keywords` Diffs by normalized text + match type; [] clears the list. Affects every campaign using it. Access: `write` · MCP tool: `replace-negative-keyword-list-keywords` · Zernio: `PUT /v1/ads/accounts/negative-keyword-lists/{listId}/keywords` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `listId` (string; required; 1–256 characters) ### Body - `keywords` (array of string | object; required; ≤ 5000 items) - one of: Option 1 (string) - one of: Option 2 (object) - `keywords.text` (string; required; 1–80 characters) - `keywords.match_type` (string; one of exact, phrase, broad) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists/LIST_ID/keywords" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "keywords": [ "string" ] }' ``` Response 200: ```json { "object": "negative_keyword_list", "id": "string", "resource_name": "string", "name": "string", "member_count": 1, "reference_count": 1, "keywords": [ { "criterion_id": "string", "text": "string", "match_type": "string" } ], "created": 1, "removed": 1 } ``` ## List account callouts `GET /ads/accounts/{adAccountId}/callouts` Google Ads callouts attached at account level. Access: `read` · MCP tool: `list-account-callouts` · Zernio: `GET /v1/ads/accounts/callouts` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/callouts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "callout", "id": "string", "status": "string", "resource_name": "string", "customer_asset_resource_name": "string", "text": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Add account callouts `POST /ads/accounts/{adAccountId}/callouts` Access: `write` · MCP tool: `add-account-callouts` · Zernio: `POST /v1/ads/accounts/callouts` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `callouts` (array of string; required; 1–20 items) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/callouts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "callouts": [ "string" ] }' ``` Response 201: ```json { "object": "list", "data": [ { "object": "callout", "id": "string", "status": "string", "resource_name": "string", "customer_asset_resource_name": "string", "text": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Update account callouts `PATCH /ads/accounts/{adAccountId}/callouts` Edits existing callout assets in place (shared assets change everywhere they are used). Access: `write` · MCP tool: `update-account-callouts` · Zernio: `PUT /v1/ads/accounts/callouts` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Body - `updates` (array of object; required; ≥ 1 items) - `updates[].asset_id` (string; required; 1–32 characters) - `updates[].text` (string; required; 1–25 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/callouts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "updates": [ { "asset_id": "string", "text": "string" } ] }' ``` Response 200: ```json { "object": "asset_update_result", "updated": 1 } ``` ## Remove an account callout `DELETE /ads/accounts/{adAccountId}/callouts/{assetId}` Detaches it from the account level only; campaign and ad group attachments stay. Access: `write` · MCP tool: `remove-account-callout` · Zernio: `DELETE /v1/ads/accounts/callouts` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `assetId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/callouts/ASSET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "callout", "id": "string", "deleted": true } ``` ## List account sitelinks `GET /ads/accounts/{adAccountId}/sitelinks` Google Ads sitelinks attached at account level. Access: `read` · MCP tool: `list-account-sitelinks` · Zernio: `GET /v1/ads/accounts/sitelinks` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/sitelinks" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "sitelink", "id": "string", "status": "string", "resource_name": "string", "customer_asset_resource_name": "string", "text": "string", "link_url": "https://example.com", "description1": "string", "description2": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Add account sitelinks `POST /ads/accounts/{adAccountId}/sitelinks` Access: `write` · MCP tool: `add-account-sitelinks` · Zernio: `POST /v1/ads/accounts/sitelinks` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `sitelinks` (array of object; required; 1–20 items) - `sitelinks[].text` (string; required; 1–25 characters) - `sitelinks[].link_url` (string (uri); required; ≤ 2048 characters) - `sitelinks[].description1` (string; 1–35 characters) - `sitelinks[].description2` (string; 1–35 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/sitelinks" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "sitelinks": [ { "text": "string", "link_url": "https://example.com" } ] }' ``` Response 201: ```json { "object": "list", "data": [ { "object": "sitelink", "id": "string", "status": "string", "resource_name": "string", "customer_asset_resource_name": "string", "text": "string", "link_url": "https://example.com", "description1": "string", "description2": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Update account sitelinks `PATCH /ads/accounts/{adAccountId}/sitelinks` Edits existing sitelink assets in place (shared assets change everywhere they are used). Access: `write` · MCP tool: `update-account-sitelinks` · Zernio: `PUT /v1/ads/accounts/sitelinks` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Body - `updates` (array of object; required; ≥ 1 items) - `updates[].asset_id` (string; required; 1–32 characters) - `updates[].text` (string; 1–25 characters) - `updates[].link_url` (string (uri); ≤ 2048 characters) - `updates[].description1` (string; 1–35 characters) - `updates[].description2` (string; 1–35 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/sitelinks" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "updates": [ { "asset_id": "string", "text": "string" } ] }' ``` Response 200: ```json { "object": "asset_update_result", "updated": 1 } ``` ## Remove an account sitelink `DELETE /ads/accounts/{adAccountId}/sitelinks/{assetId}` Detaches it from the account level only; campaign and ad group attachments stay. Access: `write` · MCP tool: `remove-account-sitelink` · Zernio: `DELETE /v1/ads/accounts/sitelinks` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `assetId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/sitelinks/ASSET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "sitelink", "id": "string", "deleted": true } ``` ## List account structured snippets `GET /ads/accounts/{adAccountId}/structured-snippets` Google Ads structured snippets attached at account level. Access: `read` · MCP tool: `list-account-structured-snippets` · Zernio: `GET /v1/ads/accounts/structured-snippets` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/structured-snippets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "structured_snippet", "id": "string", "status": "string", "resource_name": "string", "customer_asset_resource_name": "string", "header": "string", "values": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Add account structured snippets `POST /ads/accounts/{adAccountId}/structured-snippets` Access: `write` · MCP tool: `add-account-structured-snippets` · Zernio: `POST /v1/ads/accounts/structured-snippets` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `structured_snippets` (array of object; required; 1–20 items) - `structured_snippets[].header` (string; required; one of Amenities, Brands, Courses, Degree programs, Destinations, Featured hotels, Insurance coverage, Models, Neighborhoods, Service catalog, Shows, Styles, …) - `structured_snippets[].values` (array of string; required; 3–10 items) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/structured-snippets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "structured_snippets": [ { "header": "Amenities", "values": [ "string" ] } ] }' ``` Response 201: ```json { "object": "list", "data": [ { "object": "structured_snippet", "id": "string", "status": "string", "resource_name": "string", "customer_asset_resource_name": "string", "header": "string", "values": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Update account structured snippets `PATCH /ads/accounts/{adAccountId}/structured-snippets` Edits existing structured snippet assets in place (shared assets change everywhere they are used). Access: `write` · MCP tool: `update-account-structured-snippets` · Zernio: `PUT /v1/ads/accounts/structured-snippets` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Body - `updates` (array of object; required; ≥ 1 items) - `updates[].asset_id` (string; required; 1–32 characters) - `updates[].header` (string; one of Amenities, Brands, Courses, Degree programs, Destinations, Featured hotels, Insurance coverage, Models, Neighborhoods, Service catalog, Shows, Styles, …) - `updates[].values` (array of string; 3–10 items) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/structured-snippets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "updates": [ { "asset_id": "string", "header": "Amenities" } ] }' ``` Response 200: ```json { "object": "asset_update_result", "updated": 1 } ``` ## Remove an account structured snippet `DELETE /ads/accounts/{adAccountId}/structured-snippets/{assetId}` Detaches it from the account level only; campaign and ad group attachments stay. Access: `write` · MCP tool: `remove-account-structured-snippet` · Zernio: `DELETE /v1/ads/accounts/structured-snippets` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `assetId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/structured-snippets/ASSET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "structured_snippet", "id": "string", "deleted": true } ``` ## List comments on an ad `GET /ads/{adId}/comments` Comments on the ad’s post, dark posts included (Meta: Facebook or Instagram placement; TikTok). Access: `read` · MCP tool: `list-ad-comments` · Zernio: `GET /v1/ads/{adId}/comments` ### Path parameters - `adId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `placement` (string; one of facebook, instagram) - `since` (string; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD - `until` (string; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/AD_ID/comments" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "ad_comment", "id": "string", "ad_id": "string", "platform": "string", "placement": "string", "parent_id": "string", "text": "string", "author": { "id": "string", "name": "string", "username": "string" }, "like_count": 1, "reply_count": 1, "hidden": true, "can_reply": true, "can_hide": true, "can_delete": true, "created_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Reply to an ad comment `POST /ads/{adId}/comments/{commentId}/reply` Access: `write` · MCP tool: `reply-ad-comment` · Zernio: `POST /v1/ads/{adId}/comments/{commentId}/reply` ### Path parameters - `adId` (string; required; 1–256 characters) - `commentId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `text` (string; required; 1–500 characters) - `placement` (string; one of facebook, instagram) ```bash curl -X POST "https://api.socialit.com/v1/ads/AD_ID/comments/COMMENT_ID/reply" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "text": "string", "placement": "facebook" }' ``` Response 201: ```json { "object": "ad_comment", "id": "string", "ad_id": "string", "platform": "string", "placement": "string", "parent_id": "string", "text": "string", "author": { "id": "string", "name": "string", "username": "string" }, "like_count": 1, "reply_count": 1, "hidden": true, "can_reply": true, "can_hide": true, "can_delete": true, "created_at": "2026-10-13T09:00:00.000Z" } ``` ## Hide or unhide an ad comment `POST /ads/{adId}/comments/{commentId}/hide` Access: `write` · MCP tool: `hide-ad-comment` · Zernio: `POST /v1/ads/{adId}/comments/{commentId}/hide` ### Path parameters - `adId` (string; required; 1–256 characters) - `commentId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `hidden` (boolean; required) - `placement` (string; one of facebook, instagram) ```bash curl -X POST "https://api.socialit.com/v1/ads/AD_ID/comments/COMMENT_ID/hide" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "hidden": true, "placement": "facebook" }' ``` Response 200: ```json { "object": "ad_comment", "id": "string", "hidden": true } ``` ## Delete an ad comment `DELETE /ads/{adId}/comments/{commentId}` Access: `write` · MCP tool: `delete-ad-comment` · Zernio: `DELETE /v1/ads/{adId}/comments/{commentId}` ### Path parameters - `adId` (string; required; 1–256 characters) - `commentId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `placement` (string; one of facebook, instagram) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/AD_ID/comments/COMMENT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_comment", "id": "string", "deleted": true } ``` ## Get ad URL tracking params `GET /ads/{adId}/tracking-tags` Click-URL tracking parameters (UTMs), not pixels: Meta creative url_tags, Google campaign tracking template / final URL suffix, LinkedIn Dynamic UTMs. Access: `read` · MCP tool: `get-ad-tracking-params` · Zernio: `GET /v1/ads/{adId}/tracking-tags` ### Path parameters - `adId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `campaign_id` (string; 1–64 characters) ```bash curl "https://api.socialit.com/v1/ads/AD_ID/tracking-tags" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "ad_tracking_params", "ad_id": "string", "platform": "string", "level": "string", "url_tags": "string", "template_url_spec": {}, "tracking_url_template": "string", "final_url_suffix": "string", "dynamic_value_parameters": {}, "custom_value_parameters": {} } ``` ## Set ad URL tracking params `PATCH /ads/{adId}/tracking-tags` Meta rebuilds the (immutable) creative with the new url_tags and repoints the ad. Access: `write` · MCP tool: `set-ad-tracking-params` · Zernio: `PATCH /v1/ads/{adId}/tracking-tags` ### Path parameters - `adId` (string; required; 1–256 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `campaign_id` (string; 1–64 characters) - `url_tags` (array of object; ≤ 50 items) - `url_tags[].key` (string; required; 1–100 characters) - `url_tags[].value` (string; required; ≤ 500 characters) - `creative` (object) - `creative.headline` (string; required; 1–255 characters) - `creative.body` (string; required; ≤ 5000 characters) - `creative.call_to_action` (string; required; 1–64 characters) - `creative.link_url` (string (uri); required; ≤ 2048 characters) - `creative.image_url` (string (uri); ≤ 2048 characters) - `creative.video_url` (string (uri); ≤ 2048 characters) - `creative.video_id` (string; 1–64 characters) - `tracking_url_template` (string; ≤ 2048 characters) - `final_url_suffix` (string; ≤ 2048 characters) - `dynamic_value_parameters` (map of string) - `custom_value_parameters` (map of string) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/AD_ID/tracking-tags" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "campaign_id": "string", "url_tags": [ { "key": "string", "value": "string" } ] }' ``` Response 200: ```json { "object": "ad_tracking_params", "ad_id": "string", "platform": "string", "level": "string", "url_tags": "string", "template_url_spec": {}, "tracking_url_template": "string", "final_url_suffix": "string", "dynamic_value_parameters": {}, "custom_value_parameters": {} } ``` ## List tracking tags `GET /ads/accounts/{adAccountId}/tracking-tags` Pixels and measurement tags of the ad account (install code omitted). Access: `read` · MCP tool: `list-tracking-tags` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "tracking_tag", "id": "string", "site_tag_id": "string", "platform": "string", "kind": "string", "name": "string", "status": "string", "code": "string", "last_fired_at": "2026-10-13T09:00:00.000Z", "is_unavailable": true, "created_at": "2026-10-13T09:00:00.000Z", "automatic_matching_fields": [ "string" ], "owner_business_id": "string", "owner_ad_account_id": "string", "auto_tagging": true, "events": [ { "object": "tracking_tag_event", "id": "string", "name": "string", "type": "string", "site_event": "string", "site_event_id": "string" } ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a tracking tag `POST /ads/accounts/{adAccountId}/tracking-tags` Not idempotent on the networks: send an Idempotency-Key and never retry blindly. Access: `write` · MCP tool: `create-tracking-tag` · Zernio: `POST /v1/accounts/{accountId}/tracking-tags` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–100 characters) - `automatic_matching_fields` (array of string) - `default_event_type` (string; 1–64 characters) - `domain` (string; 1–255 characters) - `partner_name` (string; 1–64 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "automatic_matching_fields": [ "em" ], "default_event_type": "string", "domain": "string", "partner_name": "string" }' ``` Response 201: ```json { "object": "tracking_tag", "id": "string", "site_tag_id": "string", "platform": "string", "kind": "string", "name": "string", "status": "string", "code": "string", "last_fired_at": "2026-10-13T09:00:00.000Z", "is_unavailable": true, "created_at": "2026-10-13T09:00:00.000Z", "automatic_matching_fields": [ "string" ], "owner_business_id": "string", "owner_ad_account_id": "string", "auto_tagging": true, "events": [ { "object": "tracking_tag_event", "id": "string", "name": "string", "type": "string", "site_event": "string", "site_event_id": "string", "status": "string", "default_value": 1.5, "currency": "USD", "click_window_days": 1.5, "view_window_days": 1.5, "url_contains": "string", "always_use_default_value": true, "primary": true, "counting_type": "string" } ] } ``` ## Get a tracking tag `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}` The tag with its install code and conversion events. Access: `read` · MCP tool: `get-tracking-tag` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "tracking_tag", "id": "string", "site_tag_id": "string", "platform": "string", "kind": "string", "name": "string", "status": "string", "code": "string", "last_fired_at": "2026-10-13T09:00:00.000Z", "is_unavailable": true, "created_at": "2026-10-13T09:00:00.000Z", "automatic_matching_fields": [ "string" ], "owner_business_id": "string", "owner_ad_account_id": "string", "auto_tagging": true, "events": [ { "object": "tracking_tag_event", "id": "string", "name": "string", "type": "string", "site_event": "string", "site_event_id": "string", "status": "string", "default_value": 1.5, "currency": "USD", "click_window_days": 1.5, "view_window_days": 1.5, "url_contains": "string", "always_use_default_value": true, "primary": true, "counting_type": "string" } ] } ``` ## Update a tracking tag `PATCH /ads/accounts/{adAccountId}/tracking-tags/{tagId}` Access: `write` · MCP tool: `update-tracking-tag` · Zernio: `PATCH /v1/accounts/{accountId}/tracking-tags/{tagId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ### Body - `name` (string; 1–100 characters) - `enable_automatic_matching` (boolean) - `automatic_matching_fields` (array of string) - `first_party_cookie_status` (string; one of empty, first_party_cookie_disabled, first_party_cookie_enabled) - `data_use_setting` (string; one of advertising_and_analytics, analytics_only, empty) - `auto_tagging` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "enable_automatic_matching": true, "automatic_matching_fields": [ "em" ], "first_party_cookie_status": "empty", "data_use_setting": "advertising_and_analytics" }' ``` Response 200: ```json { "object": "tracking_tag", "id": "string", "site_tag_id": "string", "platform": "string", "kind": "string", "name": "string", "status": "string", "code": "string", "last_fired_at": "2026-10-13T09:00:00.000Z", "is_unavailable": true, "created_at": "2026-10-13T09:00:00.000Z", "automatic_matching_fields": [ "string" ], "owner_business_id": "string", "owner_ad_account_id": "string", "auto_tagging": true, "events": [ { "object": "tracking_tag_event", "id": "string", "name": "string", "type": "string", "site_event": "string", "site_event_id": "string", "status": "string", "default_value": 1.5, "currency": "USD", "click_window_days": 1.5, "view_window_days": 1.5, "url_contains": "string", "always_use_default_value": true, "primary": true, "counting_type": "string" } ] } ``` ## List accounts a tag is shared with `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/shared-accounts` Access: `read` · MCP tool: `list-tracking-tag-shared-accounts` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ### Query parameters - `business_id` (string; 1–64 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/shared-accounts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "tracking_tag_shared_account", "id": "string", "name": "string", "business_id": "string", "role": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Share a tag with an ad account `POST /ads/accounts/{adAccountId}/tracking-tags/{tagId}/shared-accounts` Access: `write` · MCP tool: `share-tracking-tag` · Zernio: `POST /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; required; 1–256 characters) - `business_id` (string; 1–64 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/shared-accounts" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "string", "business_id": "string" }' ``` Response 201: ```json { "object": "tracking_tag_shared_account", "id": "string", "name": "string", "business_id": "string", "role": "string" } ``` ## Stop sharing a tag with an account `DELETE /ads/accounts/{adAccountId}/tracking-tags/{tagId}/shared-accounts/{sharedAccountId}` Access: `write` · MCP tool: `unshare-tracking-tag` · Zernio: `DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) - `sharedAccountId` (string; required; 1–256 characters) ### Query parameters - `business_id` (string; 1–64 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/shared-accounts/SHARED_ACCOUNT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "tracking_tag_shared_account", "id": "string", "deleted": true } ``` ## List conversion events of a tag `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events` Access: `read` · MCP tool: `list-tracking-tag-events` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/events` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/events" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "tracking_tag_event", "id": "string", "name": "string", "type": "string", "site_event": "string", "site_event_id": "string", "status": "string", "default_value": 1.5, "currency": "USD", "click_window_days": 1.5, "view_window_days": 1.5, "url_contains": "string", "always_use_default_value": true, "primary": true, "counting_type": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a conversion event `POST /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events` Not idempotent on the networks. A field the network does not store → 422. Access: `write` · MCP tool: `create-tracking-tag-event` · Zernio: `POST /v1/accounts/{accountId}/tracking-tags/{tagId}/events` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–100 characters) - `type` (string; 1–64 characters) - `site_event` (string; one of page_view, view_content, add_to_cart, search, initiate_checkout, add_payment_info, purchase) - `enabled` (boolean) - `default_value` (number) - `currency` (string; pattern ^[A-Za-z]{3}$) - `click_window_days` (integer; 1–365) - `view_window_days` (integer; 0–365) - `url_contains` (string; 1–500 characters) - `counting_type` (string; one of one, every) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/events" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "type": "string", "site_event": "page_view", "enabled": true, "default_value": 0 }' ``` Response 201: ```json { "object": "tracking_tag_event", "id": "string", "name": "string", "type": "string", "site_event": "string", "site_event_id": "string", "status": "string", "default_value": 1.5, "currency": "USD", "click_window_days": 1.5, "view_window_days": 1.5, "url_contains": "string", "always_use_default_value": true, "primary": true, "counting_type": "string" } ``` ## Update a conversion event `PATCH /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events/{eventId}` Access: `write` · MCP tool: `update-tracking-tag-event` · Zernio: `PATCH /v1/accounts/{accountId}/tracking-tags/{tagId}/events/{eventId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) - `eventId` (string; required; 1–256 characters) ### Body - `name` (string; 1–100 characters) - `type` (string; 1–64 characters) - `site_event` (string; one of page_view, view_content, add_to_cart, search, initiate_checkout, add_payment_info, purchase) - `enabled` (boolean) - `default_value` (number) - `currency` (string; pattern ^[A-Za-z]{3}$) - `click_window_days` (integer; 1–365) - `view_window_days` (integer; 0–365) - `url_contains` (string; 1–500 characters) - `counting_type` (string; one of one, every) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/events/EVENT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "type": "string", "site_event": "page_view", "enabled": true, "default_value": 0 }' ``` Response 200: ```json { "object": "tracking_tag_event", "id": "string", "name": "string", "type": "string", "site_event": "string", "site_event_id": "string", "status": "string", "default_value": 1.5, "currency": "USD", "click_window_days": 1.5, "view_window_days": 1.5, "url_contains": "string", "always_use_default_value": true, "primary": true, "counting_type": "string" } ``` ## Delete a conversion event `DELETE /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events/{eventId}` Archives or disables it on networks without a hard delete (state). Access: `write` · MCP tool: `delete-tracking-tag-event` · Zernio: `DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/events/{eventId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) - `eventId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/events/EVENT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "tracking_tag_event", "id": "string", "deleted": true, "state": "string" } ``` ## List tag users `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/users` Access: `read` · MCP tool: `list-tracking-tag-users` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/users` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/users" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "tracking_tag_user", "id": "string", "name": "string", "tasks": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Assign a user to a tag `POST /ads/accounts/{adAccountId}/tracking-tags/{tagId}/users` Access: `admin` · MCP tool: `assign-tracking-tag-user` · Zernio: `POST /v1/accounts/{accountId}/tracking-tags/{tagId}/users` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `user_id` (string; required; 1–64 characters) - `tasks` (array of string; required; ≥ 1 items) - `business_id` (string; 1–64 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/users" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "user_id": "string", "tasks": [ "AA_ANALYZE" ], "business_id": "string" }' ``` Response 201: ```json { "object": "tracking_tag_user", "id": "string", "name": "string", "tasks": [ "string" ] } ``` ## Remove a user from a tag `DELETE /ads/accounts/{adAccountId}/tracking-tags/{tagId}/users/{userId}` Access: `admin` · MCP tool: `remove-tracking-tag-user` · Zernio: `DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/users/{userId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) - `userId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/users/USER_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "tracking_tag_user", "id": "string", "deleted": true } ``` ## List partner businesses of a tag `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/partners` Access: `read` · MCP tool: `list-tracking-tag-partners` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/partners` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/partners" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "tracking_tag_partner", "id": "string", "name": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Get tag diagnostics `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/diagnostics` Access: `read` · MCP tool: `get-tracking-tag-diagnostics` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/diagnostics` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/diagnostics" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "tracking_tag_diagnostic", "key": "string", "title": "string", "description": "string", "result": "string", "action_url": "https://example.com" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Get aggregated tag stats `GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/stats` Access: `read` · MCP tool: `get-tracking-tag-stats` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/stats` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `tagId` (string; required; 1–256 characters) ### Query parameters - `aggregation` (string; one of event, host, url, url_by_rule, pixel_fire, device_type, device_os, browser_type, had_pii, custom_data_field, match_keys, event_source, …) - `start_time` (string | integer): ISO 8601 date-time or unix seconds - `end_time` (string | integer): ISO 8601 date-time or unix seconds ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/stats" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "tracking_tag_stats", "tag_id": "string", "platform": "string", "aggregation": "string", "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "rows": [ {} ] } ``` ## List leads `GET /ads/leads` Stored lead-gen submissions (leadgen webhooks, live form reads, LinkedIn polling). Access: `read` · MCP tool: `list-leads` · Zernio: `GET /v1/ads/leads` ### Query parameters - `page` (integer; ≥ 1) - `limit` (integer; 1–100) - `ad_account_id` (string; 1–80 characters) - `connection_id` (string; 1–80 characters) - `form_id` (string; 1–64 characters) - `platform` (string; 1–40 characters) - `ad_id` (string; 1–64 characters) - `campaign_id` (string; 1–64 characters) - `is_test` (boolean) - `is_organic` (boolean) - `source` (string; one of webhook, sync, api) - `since` (string; 1–40 characters) - `until` (string; 1–40 characters) - `sort` (string; one of submitted_at, created_at) - `order` (string; one of asc, desc) ```bash curl "https://api.socialit.com/v1/ads/leads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "lead", "id": "string", "external_id": "string", "platform": "string", "connection_id": "string", "ad_account_id": "string", "profile_id": "string", "contact_id": "string", "form_id": "string", "form_name": "string", "page_id": "string", "ad_id": "string", "ad_set_id": "string", "campaign_id": "string", "is_organic": true, "is_test": true, "fields": {}, "field_data": [ { "name": "string", "values": [] } ], "source": "string", "submitted_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get a lead `GET /ads/leads/{leadId}` Access: `read` · MCP tool: `get-lead` ### Path parameters - `leadId` (string; required; 1–80 characters) ```bash curl "https://api.socialit.com/v1/ads/leads/LEAD_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "lead", "id": "string", "external_id": "string", "platform": "string", "connection_id": "string", "ad_account_id": "string", "profile_id": "string", "contact_id": "string", "form_id": "string", "form_name": "string", "page_id": "string", "ad_id": "string", "ad_set_id": "string", "campaign_id": "string", "is_organic": true, "is_test": true, "fields": { "key": "string" }, "field_data": [ { "name": "string", "values": [ "string" ] } ], "source": "string", "submitted_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List lead forms `GET /ads/lead-forms` Meta instant forms of a Page, LinkedIn Lead Gen Forms of a sponsored account. Access: `read` · MCP tool: `list-lead-forms` · Zernio: `GET /v1/ads/lead-forms` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `page_id` (string; 1–64 characters) - `status` (string; 1–32 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/lead-forms" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "lead_form", "id": "string", "platform": "string", "name": "string", "status": "string", "locale": "en", "page_id": "string", "ad_account_id": "string", "leads_count": 1, "privacy_policy_url": "https://example.com", "follow_up_action_url": "https://example.com", "headline": "string", "description": "string", "questions": [ { "id": "string", "key": "string", "label": "string", "type": "string", "options": [] } ], "thank_you_page": { "title": "string", "body": "string", "button_text": "string", "button_type": "string", "website_url": "https://example.com" }, "created_at": "2026-10-13T09:00:00.000Z", "raw": {} } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a lead form `POST /ads/lead-forms` Access: `write` · MCP tool: `create-lead-form` · Zernio: `POST /v1/ads/lead-forms` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `name` (string; required; 1–255 characters) - `page_id` (string; 1–64 characters) - `questions` (array of object; required; 1–30 items) - `questions[].type` (string; required; 1–64 characters) - `questions[].key` (string; 1–100 characters) - `questions[].label` (string; 1–500 characters) - `questions[].inline_context` (string; 1–500 characters) - `questions[].options` (array of object; ≤ 50 items) - `questions[].options[].value` (string; required; 1–200 characters) - `questions[].options[].key` (string; 1–100 characters) - `privacy_policy_url` (string (uri); required; ≤ 2048 characters) - `privacy_policy_link_text` (string; 1–70 characters) - `follow_up_action_url` (string (uri); ≤ 2048 characters) - `locale` (string; pattern ^[a-z]{2}_[A-Z]{2}$) - `thank_you_title` (string; 1–60 characters) - `thank_you_body` (string; 1–500 characters) - `thank_you_button_text` (string; 1–60 characters) - `thank_you_button_type` (string; 1–64 characters) - `thank_you_website_url` (string (uri); ≤ 2048 characters) - `is_optimized_for_quality` (boolean) - `headline` (string; 1–60 characters) - `description` (string; 1–160 characters) - `state` (string; one of DRAFT, PUBLISHED) - `platform_data` (object) ```bash curl -X POST "https://api.socialit.com/v1/ads/lead-forms" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "name": "string", "questions": [ { "type": "string", "key": "string" } ], "privacy_policy_url": "https://example.com" }' ``` Response 201: ```json { "object": "lead_form", "id": "string", "platform": "string", "name": "string", "status": "string", "locale": "en", "page_id": "string", "ad_account_id": "string", "leads_count": 1, "privacy_policy_url": "https://example.com", "follow_up_action_url": "https://example.com", "headline": "string", "description": "string", "questions": [ { "id": "string", "key": "string", "label": "string", "type": "string", "options": [ { "value": "string", "key": "string" } ] } ], "thank_you_page": { "title": "string", "body": "string", "button_text": "string", "button_type": "string", "website_url": "https://example.com" }, "created_at": "2026-10-13T09:00:00.000Z", "raw": {} } ``` ## Get a lead form `GET /ads/lead-forms/{formId}` Access: `read` · MCP tool: `get-lead-form` · Zernio: `GET /v1/ads/lead-forms/{formId}` ### Path parameters - `formId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `page_id` (string; 1–64 characters) ```bash curl "https://api.socialit.com/v1/ads/lead-forms/FORM_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "lead_form", "id": "string", "platform": "string", "name": "string", "status": "string", "locale": "en", "page_id": "string", "ad_account_id": "string", "leads_count": 1, "privacy_policy_url": "https://example.com", "follow_up_action_url": "https://example.com", "headline": "string", "description": "string", "questions": [ { "id": "string", "key": "string", "label": "string", "type": "string", "options": [ { "value": "string", "key": "string" } ] } ], "thank_you_page": { "title": "string", "body": "string", "button_text": "string", "button_type": "string", "website_url": "https://example.com" }, "created_at": "2026-10-13T09:00:00.000Z", "raw": {} } ``` ## Archive a lead form `DELETE /ads/lead-forms/{formId}` Access: `write` · MCP tool: `archive-lead-form` · Zernio: `DELETE /v1/ads/lead-forms/{formId}` ### Path parameters - `formId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `page_id` (string; 1–64 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/lead-forms/FORM_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "lead_form", "id": "string", "archived": true, "deleted": true } ``` ## List the leads of a form `GET /ads/lead-forms/{formId}/leads` Reads the form’s leads live and stores them (new leads emit lead.received). Access: `read` · MCP tool: `list-lead-form-leads` · Zernio: `GET /v1/ads/lead-forms/{formId}/leads` ### Path parameters - `formId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `page_id` (string; 1–64 characters) - `since` (string | integer): ISO 8601 date-time or unix seconds - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/lead-forms/FORM_ID/leads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "lead", "id": "string", "external_id": "string", "platform": "string", "connection_id": "string", "ad_account_id": "string", "profile_id": "string", "contact_id": "string", "form_id": "string", "form_name": "string", "page_id": "string", "ad_id": "string", "ad_set_id": "string", "campaign_id": "string", "is_organic": true, "is_test": true, "fields": {}, "field_data": [ { "name": "string", "values": [] } ], "source": "string", "submitted_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a test lead `POST /ads/lead-forms/{formId}/test-leads` Access: `write` · MCP tool: `create-test-lead` · Zernio: `POST /v1/ads/lead-forms/{formId}/test-leads` ### Path parameters - `formId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `page_id` (string; 1–64 characters) - `field_data` (array of object; required; 1–50 items) - `field_data[].name` (string; required; 1–100 characters) - `field_data[].values` (array of string; required; ≥ 1 items) ```bash curl -X POST "https://api.socialit.com/v1/ads/lead-forms/FORM_ID/test-leads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "page_id": "string", "field_data": [ { "name": "string", "values": [ "string" ] } ] }' ``` Response 201: ```json { "object": "test_lead", "id": "string", "form_id": "string" } ``` ## Delete test leads `DELETE /ads/lead-forms/{formId}/test-leads` Access: `write` · MCP tool: `delete-test-leads` · Zernio: `DELETE /v1/ads/lead-forms/{formId}/test-leads` ### Path parameters - `formId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `page_id` (string; 1–64 characters) - `lead_id` (string; 1–64 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/lead-forms/FORM_ID/test-leads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "test_lead", "deleted": true, "ids": [ "string" ] } ``` ## List product catalogs `GET /ads/catalogs` Meta Commerce catalogs owned by (or shared with) a business portfolio. Access: `read` · MCP tool: `list-catalogs` · Zernio: `GET /v1/ads/catalogs` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/catalogs" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "catalog", "id": "string", "name": "string", "vertical": "string", "product_count": 1, "business_id": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string", "business_id": "string" } ``` ## Create a product catalog `POST /ads/catalogs` Access: `write` · MCP tool: `create-catalog` · Zernio: `POST /v1/ads/catalogs` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `name` (string; required; 1–200 characters) - `vertical` (string; one of commerce, vehicles, hotels, flights, destinations, home_listings, local_service_business, offline_commerce, ticketed_experiences, transactable_items) ```bash curl -X POST "https://api.socialit.com/v1/ads/catalogs" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "business_id": "string", "name": "string" }' ``` Response 201: ```json { "object": "catalog", "id": "string", "name": "string", "vertical": "string", "product_count": 1, "business_id": "string" } ``` ## Get a product catalog `GET /ads/catalogs/{catalogId}` Access: `read` · MCP tool: `get-catalog` · Zernio: `GET /v1/ads/catalogs/{catalogId}` ### Path parameters - `catalogId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "catalog", "id": "string", "name": "string", "vertical": "string", "product_count": 1, "business_id": "string" } ``` ## Delete a product catalog `DELETE /ads/catalogs/{catalogId}` Access: `write` · MCP tool: `delete-catalog` · Zernio: `DELETE /v1/ads/catalogs/{catalogId}` ### Path parameters - `catalogId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl -X DELETE "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "catalog", "id": "string", "deleted": true } ``` ## List catalog products `GET /ads/catalogs/{catalogId}/products` Access: `read` · MCP tool: `list-catalog-products` · Zernio: `GET /v1/ads/catalogs/{catalogId}/products` ### Path parameters - `catalogId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `retailer_id` (string; 1–100 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "catalog_product", "id": "string", "retailer_id": "string", "name": "string", "description": "string", "url": "https://example.com", "image_url": "https://example.com", "additional_image_urls": [ "string" ], "price": "string", "sale_price": "string", "currency": "USD", "availability": "string", "condition": "string", "brand": "string", "category": "string", "product_type": "string", "gtin": "string", "inventory": 1, "visibility": "string", "color": "string", "size": "string", "gender": "string", "material": "string", "pattern": "string", "custom_labels": [ "string" ], "review_status": "string", "review_rejection_reasons": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Add a product `POST /ads/catalogs/{catalogId}/products` Access: `write` · MCP tool: `create-catalog-product` · Zernio: `POST /v1/ads/catalogs/{catalogId}/products` ### Path parameters - `catalogId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `product` (object; required) - `product.retailer_id` (string; 1–100 characters) - `product.name` (string; 1–200 characters) - `product.description` (string; 1–9999 characters) - `product.url` (string (uri); ≤ 2048 characters) - `product.image_url` (string (uri); ≤ 2048 characters) - `product.additional_image_urls` (array of string (uri); ≤ 20 items) - `product.price` (number) - `product.currency` (string; pattern ^[A-Za-z]{3}$) - `product.sale_price` (number) - `product.sale_price_start_date` (string; 1–40 characters) - `product.sale_price_end_date` (string; 1–40 characters) - `product.availability` (string; one of in stock, out of stock, preorder, available for order, discontinued, pending) - `product.condition` (string; one of new, refurbished, used) - `product.brand` (string; 1–100 characters) - `product.category` (string; 1–250 characters) - `product.google_product_category` (string; 1–250 characters) - `product.product_type` (string; 1–750 characters) - `product.gtin` (string; 1–70 characters) - `product.mpn` (string; 1–100 characters) - `product.inventory` (integer) - `product.visibility` (string; one of published, staging) - `product.color` (string; 1–200 characters) - `product.size` (string; 1–200 characters) - `product.gender` (string; one of female, male, unisex) - `product.material` (string; 1–200 characters) - `product.pattern` (string; 1–100 characters) - `product.custom_label_0` (string; 1–100 characters) - `product.custom_label_1` (string; 1–100 characters) - `product.custom_label_2` (string; 1–100 characters) - `product.custom_label_3` (string; 1–100 characters) - `product.custom_label_4` (string; 1–100 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "product": { "retailer_id": "string", "name": "string" } }' ``` Response 201: ```json { "object": "catalog_product", "id": "string", "retailer_id": "string", "name": "string", "description": "string", "url": "https://example.com", "image_url": "https://example.com", "additional_image_urls": [ "string" ], "price": "string", "sale_price": "string", "currency": "USD", "availability": "string", "condition": "string", "brand": "string", "category": "string", "product_type": "string", "gtin": "string", "inventory": 1, "visibility": "string", "color": "string", "size": "string", "gender": "string", "material": "string", "pattern": "string", "custom_labels": [ "string" ], "review_status": "string", "review_rejection_reasons": [ "string" ] } ``` ## Create, update or delete products in bulk `POST /ads/catalogs/{catalogId}/products/batch` Up to 5,000 requests keyed by retailer_id, processed asynchronously (202). Access: `write` · MCP tool: `batch-catalog-products` · Zernio: `POST /v1/ads/catalogs/{catalogId}/products/batch` ### Path parameters - `catalogId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `requests` (array of object; required; 1–5000 items) - `requests[].method` (string; required; one of CREATE, UPDATE, DELETE) - `requests[].product` (object; required) - `requests[].product.retailer_id` (string; 1–100 characters) - `requests[].product.name` (string; 1–200 characters) - `requests[].product.description` (string; 1–9999 characters) - `requests[].product.url` (string (uri); ≤ 2048 characters) - `requests[].product.image_url` (string (uri); ≤ 2048 characters) - `requests[].product.additional_image_urls` (array of string (uri); ≤ 20 items) - `requests[].product.price` (number) - `requests[].product.currency` (string; pattern ^[A-Za-z]{3}$) - `requests[].product.sale_price` (number) - `requests[].product.sale_price_start_date` (string; 1–40 characters) - `requests[].product.sale_price_end_date` (string; 1–40 characters) - `requests[].product.availability` (string; one of in stock, out of stock, preorder, available for order, discontinued, pending) - `requests[].product.condition` (string; one of new, refurbished, used) - `requests[].product.brand` (string; 1–100 characters) - `requests[].product.category` (string; 1–250 characters) - `requests[].product.google_product_category` (string; 1–250 characters) - `requests[].product.product_type` (string; 1–750 characters) - `requests[].product.gtin` (string; 1–70 characters) - `requests[].product.mpn` (string; 1–100 characters) - `requests[].product.inventory` (integer) - `requests[].product.visibility` (string; one of published, staging) - `requests[].product.color` (string; 1–200 characters) - `requests[].product.size` (string; 1–200 characters) - `requests[].product.gender` (string; one of female, male, unisex) - `requests[].product.material` (string; 1–200 characters) - `requests[].product.pattern` (string; 1–100 characters) - `requests[].product.custom_label_0` (string; 1–100 characters) - `requests[].product.custom_label_1` (string; 1–100 characters) - `requests[].product.custom_label_2` (string; 1–100 characters) - `requests[].product.custom_label_3` (string; 1–100 characters) - `requests[].product.custom_label_4` (string; 1–100 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products/batch" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "requests": [ { "method": "CREATE", "product": { "retailer_id": "string", "name": "string" } } ] }' ``` Response 202: ```json { "object": "catalog_batch_request", "catalog_id": "string", "handles": [ "string" ], "status_url": "https://example.com" } ``` ## Get a bulk request’s status `GET /ads/catalogs/{catalogId}/batches/{handle}` Access: `read` · MCP tool: `get-catalog-batch` · Zernio: `GET /v1/ads/catalogs/{catalogId}/batches/{handle}` ### Path parameters - `catalogId` (string; required; 1–256 characters) - `handle` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/batches/HANDLE" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "catalog_batch", "handle": "string", "status": "string", "errors_total_count": 1, "errors": [ { "retailer_id": "string", "message": "string" } ] } ``` ## Get a product `GET /ads/catalogs/{catalogId}/products/{productId}` Access: `read` · MCP tool: `get-catalog-product` · Zernio: `GET /v1/ads/catalogs/{catalogId}/products/{productId}` ### Path parameters - `catalogId` (string; required; 1–256 characters) - `productId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products/PRODUCT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "catalog_product", "id": "string", "retailer_id": "string", "name": "string", "description": "string", "url": "https://example.com", "image_url": "https://example.com", "additional_image_urls": [ "string" ], "price": "string", "sale_price": "string", "currency": "USD", "availability": "string", "condition": "string", "brand": "string", "category": "string", "product_type": "string", "gtin": "string", "inventory": 1, "visibility": "string", "color": "string", "size": "string", "gender": "string", "material": "string", "pattern": "string", "custom_labels": [ "string" ], "review_status": "string", "review_rejection_reasons": [ "string" ] } ``` ## Update a product `PATCH /ads/catalogs/{catalogId}/products/{productId}` Access: `write` · MCP tool: `update-catalog-product` · Zernio: `PUT /v1/ads/catalogs/{catalogId}/products/{productId}` ### Path parameters - `catalogId` (string; required; 1–256 characters) - `productId` (string; required; 1–256 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `product` (object; required) - `product.retailer_id` (string; 1–100 characters) - `product.name` (string; 1–200 characters) - `product.description` (string; 1–9999 characters) - `product.url` (string (uri); ≤ 2048 characters) - `product.image_url` (string (uri); ≤ 2048 characters) - `product.additional_image_urls` (array of string (uri); ≤ 20 items) - `product.price` (number) - `product.currency` (string; pattern ^[A-Za-z]{3}$) - `product.sale_price` (number) - `product.sale_price_start_date` (string; 1–40 characters) - `product.sale_price_end_date` (string; 1–40 characters) - `product.availability` (string; one of in stock, out of stock, preorder, available for order, discontinued, pending) - `product.condition` (string; one of new, refurbished, used) - `product.brand` (string; 1–100 characters) - `product.category` (string; 1–250 characters) - `product.google_product_category` (string; 1–250 characters) - `product.product_type` (string; 1–750 characters) - `product.gtin` (string; 1–70 characters) - `product.mpn` (string; 1–100 characters) - `product.inventory` (integer) - `product.visibility` (string; one of published, staging) - `product.color` (string; 1–200 characters) - `product.size` (string; 1–200 characters) - `product.gender` (string; one of female, male, unisex) - `product.material` (string; 1–200 characters) - `product.pattern` (string; 1–100 characters) - `product.custom_label_0` (string; 1–100 characters) - `product.custom_label_1` (string; 1–100 characters) - `product.custom_label_2` (string; 1–100 characters) - `product.custom_label_3` (string; 1–100 characters) - `product.custom_label_4` (string; 1–100 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products/PRODUCT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "product": { "retailer_id": "string", "name": "string" } }' ``` Response 200: ```json { "object": "catalog_product", "id": "string", "retailer_id": "string", "name": "string", "description": "string", "url": "https://example.com", "image_url": "https://example.com", "additional_image_urls": [ "string" ], "price": "string", "sale_price": "string", "currency": "USD", "availability": "string", "condition": "string", "brand": "string", "category": "string", "product_type": "string", "gtin": "string", "inventory": 1, "visibility": "string", "color": "string", "size": "string", "gender": "string", "material": "string", "pattern": "string", "custom_labels": [ "string" ], "review_status": "string", "review_rejection_reasons": [ "string" ] } ``` ## Delete a product `DELETE /ads/catalogs/{catalogId}/products/{productId}` Access: `write` · MCP tool: `delete-catalog-product` · Zernio: `DELETE /v1/ads/catalogs/{catalogId}/products/{productId}` ### Path parameters - `catalogId` (string; required; 1–256 characters) - `productId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl -X DELETE "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products/PRODUCT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "catalog_product", "id": "string", "deleted": true } ``` ## List product feeds `GET /ads/catalogs/{catalogId}/feeds` Access: `read` · MCP tool: `list-catalog-feeds` · Zernio: `GET /v1/ads/catalogs/{catalogId}/feeds` ### Path parameters - `catalogId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/feeds" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "catalog_feed", "id": "string", "name": "string", "product_count": 1, "schedule": { "interval": "string", "url": "https://example.com", "hour": 1, "day_of_week": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "latest_upload": { "object": "catalog_feed_upload", "id": "string", "url": "https://example.com", "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "error_count": 1 } } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a product feed `POST /ads/catalogs/{catalogId}/feeds` Access: `write` · MCP tool: `create-catalog-feed` · Zernio: `POST /v1/ads/catalogs/{catalogId}/feeds` ### Path parameters - `catalogId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `name` (string; required; 1–200 characters) - `schedule` (object) - `schedule.interval` (string; required; one of HOURLY, DAILY, WEEKLY) - `schedule.url` (string (uri); required; ≤ 2048 characters) - `schedule.hour` (integer; 0–23) - `schedule.day_of_week` (string; one of SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY) ```bash curl -X POST "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/feeds" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "schedule": { "interval": "HOURLY", "url": "https://example.com" } }' ``` Response 201: ```json { "object": "catalog_feed", "id": "string", "name": "string", "product_count": 1, "schedule": { "interval": "string", "url": "https://example.com", "hour": 1, "day_of_week": "string" }, "created_at": "2026-10-13T09:00:00.000Z", "latest_upload": { "object": "catalog_feed_upload", "id": "string", "url": "https://example.com", "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "error_count": 1, "warning_count": 1, "items_detected": 1, "items_deleted": 1 } } ``` ## List a feed’s uploads `GET /ads/catalogs/{catalogId}/feeds/{feedId}/uploads` Access: `read` · MCP tool: `list-catalog-feed-uploads` · Zernio: `GET /v1/ads/catalogs/{catalogId}/feeds/{feedId}/uploads` ### Path parameters - `catalogId` (string; required; 1–256 characters) - `feedId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/feeds/FEED_ID/uploads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "catalog_feed_upload", "id": "string", "url": "https://example.com", "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "error_count": 1, "warning_count": 1, "items_detected": 1, "items_deleted": 1 } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Fetch a feed file now `POST /ads/catalogs/{catalogId}/feeds/{feedId}/uploads` Access: `write` · MCP tool: `create-catalog-feed-upload` · Zernio: `POST /v1/ads/catalogs/{catalogId}/feeds/{feedId}/uploads` ### Path parameters - `catalogId` (string; required; 1–256 characters) - `feedId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `url` (string (uri); required; ≤ 2048 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/feeds/FEED_ID/uploads" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "url": "https://example.com" }' ``` Response 202: ```json { "object": "catalog_feed_upload", "id": "string", "url": "https://example.com", "start_time": "2026-10-13T09:00:00.000Z", "end_time": "2026-10-13T09:00:00.000Z", "error_count": 1, "warning_count": 1, "items_detected": 1, "items_deleted": 1 } ``` ## List product sets `GET /ads/catalogs/{catalogId}/product-sets` Access: `read` · MCP tool: `list-product-sets` · Zernio: `GET /v1/ads/catalogs/{catalogId}/product-sets` ### Path parameters - `catalogId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/product-sets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "product_set", "id": "string", "name": "string", "product_count": 1, "filter": {} } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a product set `POST /ads/catalogs/{catalogId}/product-sets` Access: `write` · MCP tool: `create-product-set` · Zernio: `POST /v1/ads/catalogs/{catalogId}/product-sets` ### Path parameters - `catalogId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `name` (string; required; 1–200 characters) - `filter` (object; required) ```bash curl -X POST "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/product-sets" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "filter": {} }' ``` Response 201: ```json { "object": "product_set", "id": "string", "name": "string", "product_count": 1, "filter": {} } ``` ## Update a product set `PATCH /ads/catalogs/{catalogId}/product-sets/{productSetId}` Access: `write` · MCP tool: `update-product-set` · Zernio: `PUT /v1/ads/catalogs/{catalogId}/product-sets/{productSetId}` ### Path parameters - `catalogId` (string; required; 1–256 characters) - `productSetId` (string; required; 1–256 characters) ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `name` (string; 1–200 characters) - `filter` (object) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/product-sets/PRODUCT_SET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "name": "string", "filter": {} }' ``` Response 200: ```json { "object": "product_set", "id": "string", "name": "string", "product_count": 1, "filter": {} } ``` ## Delete a product set `DELETE /ads/catalogs/{catalogId}/product-sets/{productSetId}` Access: `write` · MCP tool: `delete-product-set` · Zernio: `DELETE /v1/ads/catalogs/{catalogId}/product-sets/{productSetId}` ### Path parameters - `catalogId` (string; required; 1–256 characters) - `productSetId` (string; required; 1–256 characters) ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `business_id` (string; 1–64 characters) - `limit` (integer; 1–100): Items per page (max 100) - `cursor` (string; ≤ 4096 characters): next_cursor from the previous page - `after` (string; ≤ 4096 characters): Alias of cursor ```bash curl -X DELETE "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/product-sets/PRODUCT_SET_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "product_set", "id": "string", "deleted": true } ``` ## Send conversion events `POST /ads/conversions` Relays server-side conversion events (PII normalized + SHA-256 hashed, never stored) to the network Conversions API. Access: `write` · MCP tool: `send-conversions` · Zernio: `POST /v1/ads/conversions` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `destination_id` (string; required; 1–256 characters) - `events` (array of object; required; 1–1000 items) - `events[].event_name` (string; required; 1–100 characters) - `events[].event_time` (string | integer; required): ISO 8601 date-time or unix seconds - `events[].event_id` (string; required; 1–100 characters) - `events[].value` (number) - `events[].currency` (string; pattern ^[A-Za-z]{3}$) - `events[].user` (object; required) - `events[].user.email` (string; 1–320 characters) - `events[].user.emails` (array of string; ≤ 10 items) - `events[].user.phone` (string; 1–64 characters) - `events[].user.phones` (array of string; ≤ 10 items) - `events[].user.first_name` (string; 1–200 characters) - `events[].user.last_name` (string; 1–200 characters) - `events[].user.city` (string; 1–200 characters) - `events[].user.state` (string; 1–100 characters) - `events[].user.zip` (string; 1–32 characters) - `events[].user.country` (string; 1–64 characters) - `events[].user.date_of_birth` (string; 1–16 characters) - `events[].user.gender` (string; 1–16 characters) - `events[].user.external_id` (string; 1–256 characters) - `events[].user.external_ids` (array of string; ≤ 10 items) - `events[].user.ip_address` (string; 1–64 characters) - `events[].user.user_agent` (string; 1–1024 characters) - `events[].user.company_name` (string; 1–200 characters) - `events[].user.title` (string; 1–200 characters) - `events[].user.fbc` (string; 1–500 characters) - `events[].user.fbp` (string; 1–500 characters) - `events[].user.gclid` (string; 1–500 characters) - `events[].user.gbraid` (string; 1–500 characters) - `events[].user.wbraid` (string; 1–500 characters) - `events[].user.ttclid` (string; 1–500 characters) - `events[].user.ttp` (string; 1–500 characters) - `events[].user.li_fat_id` (string; 1–500 characters) - `events[].user.epik` (string; 1–500 characters) - `events[].user.sc_click_id` (string; 1–500 characters) - `events[].user.sc_cookie1` (string; 1–500 characters) - `events[].user.rdt_cid` (string; 1–500 characters) - `events[].user.twclid` (string; 1–500 characters) - `events[].user.click_id` (string; 1–500 characters) - `events[].user.lead_id` (string; 1–64 characters) - `events[].user.uuid` (string; 1–200 characters) - `events[].user.hashed` (boolean) - `events[].items` (array of object; ≤ 200 items) - `events[].items[].id` (string; required; 1–100 characters) - `events[].items[].quantity` (integer; ≥ 1) - `events[].items[].price` (number) - `events[].items[].name` (string; 1–200 characters) - `events[].items[].category` (string; 1–200 characters) - `events[].source_url` (string (uri); ≤ 2048 characters) - `events[].action_source` (string; one of web, app, offline, crm, phone_call, system_generated) - `events[].order_id` (string; 1–100 characters) - `events[].platform_data` (object) - `test_code` (string; 1–100 characters) - `consent` (object) - `consent.ad_user_data` (string; one of GRANTED, DENIED) - `consent.ad_personalization` (string; one of GRANTED, DENIED) ```bash curl -X POST "https://api.socialit.com/v1/ads/conversions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "destination_id": "string", "events": [ { "event_name": "string", "event_time": "string", "event_id": "string", "user": { "email": "you@example.com", "emails": [ "string" ] } } ] }' ``` Response 200: ```json { "object": "conversion_result", "platform": "string", "ad_account_id": "string", "destination_id": "string", "test": true, "events_received": 1, "events_failed": 1, "failures": [ { "index": 1, "event_id": "string", "message": "string", "code": "string" } ], "trace_id": "string" } ``` ## Adjust uploaded conversions `POST /ads/conversions/adjustments` Retract, restate or enhance conversions already sent (Google Ads). Access: `write` · MCP tool: `adjust-conversions` · Zernio: `POST /v1/ads/conversions/adjustments` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `destination_id` (string; required; 1–64 characters) - `adjustments` (array of object; required; 1–2000 items) - `adjustments[].adjustment_type` (string; required; one of RETRACTION, RESTATEMENT, ENHANCEMENT) - `adjustments[].adjustment_time` (string | integer; required): ISO 8601 date-time or unix seconds - `adjustments[].order_id` (string; 1–100 characters) - `adjustments[].gclid` (string; 1–500 characters) - `adjustments[].conversion_time` (string | integer): ISO 8601 date-time or unix seconds - `adjustments[].restatement_value` (number) - `adjustments[].currency` (string; pattern ^[A-Za-z]{3}$) - `adjustments[].user` (object) - `adjustments[].user.email` (string; 1–320 characters) - `adjustments[].user.emails` (array of string; ≤ 10 items) - `adjustments[].user.phone` (string; 1–64 characters) - `adjustments[].user.phones` (array of string; ≤ 10 items) - `adjustments[].user.first_name` (string; 1–200 characters) - `adjustments[].user.last_name` (string; 1–200 characters) - `adjustments[].user.city` (string; 1–200 characters) - `adjustments[].user.state` (string; 1–100 characters) - `adjustments[].user.zip` (string; 1–32 characters) - `adjustments[].user.country` (string; 1–64 characters) - `adjustments[].user.date_of_birth` (string; 1–16 characters) - `adjustments[].user.gender` (string; 1–16 characters) - `adjustments[].user.external_id` (string; 1–256 characters) - `adjustments[].user.external_ids` (array of string; ≤ 10 items) - `adjustments[].user.ip_address` (string; 1–64 characters) - `adjustments[].user.user_agent` (string; 1–1024 characters) - `adjustments[].user.company_name` (string; 1–200 characters) - `adjustments[].user.title` (string; 1–200 characters) - `adjustments[].user.fbc` (string; 1–500 characters) - `adjustments[].user.fbp` (string; 1–500 characters) - `adjustments[].user.gclid` (string; 1–500 characters) - `adjustments[].user.gbraid` (string; 1–500 characters) - `adjustments[].user.wbraid` (string; 1–500 characters) - `adjustments[].user.ttclid` (string; 1–500 characters) - `adjustments[].user.ttp` (string; 1–500 characters) - `adjustments[].user.li_fat_id` (string; 1–500 characters) - `adjustments[].user.epik` (string; 1–500 characters) - `adjustments[].user.sc_click_id` (string; 1–500 characters) - `adjustments[].user.sc_cookie1` (string; 1–500 characters) - `adjustments[].user.rdt_cid` (string; 1–500 characters) - `adjustments[].user.twclid` (string; 1–500 characters) - `adjustments[].user.click_id` (string; 1–500 characters) - `adjustments[].user.lead_id` (string; 1–64 characters) - `adjustments[].user.uuid` (string; 1–200 characters) - `adjustments[].user.hashed` (boolean) - `adjustments[].user_agent` (string; 1–1024 characters) ```bash curl -X POST "https://api.socialit.com/v1/ads/conversions/adjustments" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "platform_ad_account_id": "string", "destination_id": "string", "adjustments": [ { "adjustment_type": "RETRACTION", "adjustment_time": "string" } ] }' ``` Response 200: ```json { "object": "conversion_adjustment_result", "platform": "string", "ad_account_id": "string", "destination_id": "string", "adjustments_received": 1, "adjustments_failed": 1, "failures": [ { "index": 1, "message": "string", "code": "string" } ], "trace_id": "string" } ``` ## Get Event Match Quality `GET /ads/conversions/quality` Access: `read` · MCP tool: `get-event-match-quality` · Zernio: `GET /v1/ads/conversions/quality` ### Query parameters - `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…) - `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts - `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …) - `destination_id` (string; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/conversions/quality" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "event_match_quality", "platform": "string", "destination_id": "string", "rows": [ { "event_name": "string", "composite_score": 1.5, "match_keys": [ { "identifier": "string", "coverage_percentage": 1.5 } ], "event_coverage_percentage": 1.5 } ] } ``` ## List conversion actions `GET /ads/accounts/{adAccountId}/conversion-actions` Google Ads conversion actions with their tag snippets. Access: `read` · MCP tool: `list-conversion-actions` · Zernio: `GET /v1/ads/conversions/actions` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `type` (string; 1–64 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-actions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "conversion_action", "id": "string", "name": "string", "type": "string", "status": "string", "category": "string", "origin": "string", "primary_for_goal": true, "default_value": 1.5, "default_currency": "string", "always_use_default_value": true, "counting_type": "string", "click_through_lookback_window_days": 1.5, "view_through_lookback_window_days": 1.5, "resource_name": "string", "tag_snippets": [ { "type": "string", "page_format": "string", "global_site_tag": "string", "event_snippet": "string" } ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a website conversion action `POST /ads/accounts/{adAccountId}/conversion-actions` Access: `write` · MCP tool: `create-conversion-action` · Zernio: `POST /v1/ads/conversions/actions` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–255 characters) - `category` (string; one of DEFAULT, PAGE_VIEW, PURCHASE, SIGNUP, DOWNLOAD, ADD_TO_CART, BEGIN_CHECKOUT, SUBSCRIBE_PAID, PHONE_CALL_LEAD, IMPORTED_LEAD, SUBMIT_LEAD_FORM, BOOK_APPOINTMENT, …) - `default_value` (number) - `default_currency` (string; pattern ^[A-Za-z]{3}$) - `always_use_default_value` (boolean) - `counting_type` (string; one of ONE_PER_CLICK, MANY_PER_CLICK) - `click_through_lookback_window_days` (integer; 1–90) - `view_through_lookback_window_days` (integer; 1–30) - `primary_for_goal` (boolean) - `type` (string; one of WEBPAGE) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-actions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "category": "DEFAULT", "default_value": 0, "default_currency": "string", "always_use_default_value": true }' ``` Response 201: ```json { "object": "conversion_action", "id": "string", "name": "string", "type": "string", "status": "string", "category": "string", "origin": "string", "primary_for_goal": true, "default_value": 1.5, "default_currency": "string", "always_use_default_value": true, "counting_type": "string", "click_through_lookback_window_days": 1.5, "view_through_lookback_window_days": 1.5, "resource_name": "string", "tag_snippets": [ { "type": "string", "page_format": "string", "global_site_tag": "string", "event_snippet": "string" } ] } ``` ## Update a conversion action `PATCH /ads/accounts/{adAccountId}/conversion-actions/{actionId}` Access: `write` · MCP tool: `update-conversion-action` · Zernio: `PATCH /v1/ads/conversions/actions/{actionId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `actionId` (string; required; 1–256 characters) ### Body - `name` (string; 1–255 characters) - `category` (string; one of DEFAULT, PAGE_VIEW, PURCHASE, SIGNUP, DOWNLOAD, ADD_TO_CART, BEGIN_CHECKOUT, SUBSCRIBE_PAID, PHONE_CALL_LEAD, IMPORTED_LEAD, SUBMIT_LEAD_FORM, BOOK_APPOINTMENT, …) - `default_value` (number) - `default_currency` (string; pattern ^[A-Za-z]{3}$) - `always_use_default_value` (boolean) - `counting_type` (string; one of ONE_PER_CLICK, MANY_PER_CLICK) - `click_through_lookback_window_days` (integer; 1–90) - `view_through_lookback_window_days` (integer; 1–30) - `primary_for_goal` (boolean) - `status` (string; one of ENABLED, REMOVED) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-actions/ACTION_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "category": "DEFAULT", "default_value": 0, "default_currency": "string", "always_use_default_value": true }' ``` Response 200: ```json { "object": "conversion_action", "id": "string", "name": "string", "type": "string", "status": "string", "category": "string", "origin": "string", "primary_for_goal": true, "default_value": 1.5, "default_currency": "string", "always_use_default_value": true, "counting_type": "string", "click_through_lookback_window_days": 1.5, "view_through_lookback_window_days": 1.5, "resource_name": "string", "tag_snippets": [ { "type": "string", "page_format": "string", "global_site_tag": "string", "event_snippet": "string" } ] } ``` ## List account conversion goals `GET /ads/accounts/{adAccountId}/conversion-goals` Access: `read` · MCP tool: `list-conversion-goals` · Zernio: `GET /v1/ads/conversions/goals` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-goals" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "conversion_goal", "category": "string", "origin": "string", "biddable": true, "resource_name": "string", "conversion_actions": [ { "id": "string", "name": "string", "status": "string", "primary_for_goal": true } ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Update account conversion goals `PATCH /ads/accounts/{adAccountId}/conversion-goals` Access: `write` · MCP tool: `update-conversion-goals` · Zernio: `PATCH /v1/ads/conversions/goals` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Body - `goals` (array of object; required; 1–100 items) - `goals[].category` (string; required; 1–64 characters) - `goals[].origin` (string; required; 1–64 characters) - `goals[].biddable` (boolean; required) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-goals" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "goals": [ { "category": "string", "origin": "string", "biddable": true } ] }' ``` Response 200: ```json { "object": "list", "data": [ { "object": "conversion_goal", "category": "string", "origin": "string", "biddable": true, "resource_name": "string", "conversion_actions": [ { "id": "string", "name": "string", "status": "string", "primary_for_goal": true } ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## List custom conversion goals `GET /ads/accounts/{adAccountId}/custom-conversion-goals` Access: `read` · MCP tool: `list-custom-conversion-goals` · Zernio: `GET /v1/ads/conversions/custom-goals` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversion-goals" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "custom_conversion_goal", "id": "string", "resource_name": "string", "name": "string", "status": "string", "conversion_action_ids": [ "string" ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a custom conversion goal `POST /ads/accounts/{adAccountId}/custom-conversion-goals` Access: `write` · MCP tool: `create-custom-conversion-goal` · Zernio: `POST /v1/ads/conversions/custom-goals` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–255 characters) - `conversion_action_ids` (array of string; required; 1–100 items) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversion-goals" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "conversion_action_ids": [ "string" ] }' ``` Response 201: ```json { "object": "custom_conversion_goal", "id": "string", "resource_name": "string", "name": "string", "status": "string", "conversion_action_ids": [ "string" ] } ``` ## Update a custom conversion goal `PATCH /ads/accounts/{adAccountId}/custom-conversion-goals/{goalId}` Access: `write` · MCP tool: `update-custom-conversion-goal` · Zernio: `PATCH /v1/ads/conversions/custom-goals/{goalId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `goalId` (string; required; 1–256 characters) ### Body - `name` (string; 1–255 characters) - `conversion_action_ids` (array of string; 1–100 items) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversion-goals/GOAL_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "conversion_action_ids": [ "string" ] }' ``` Response 200: ```json { "object": "custom_conversion_goal", "id": "string", "resource_name": "string", "name": "string", "status": "string", "conversion_action_ids": [ "string" ] } ``` ## Remove a custom conversion goal `DELETE /ads/accounts/{adAccountId}/custom-conversion-goals/{goalId}` Access: `write` · MCP tool: `delete-custom-conversion-goal` · Zernio: `DELETE /v1/ads/conversions/custom-goals/{goalId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `goalId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversion-goals/GOAL_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "custom_conversion_goal", "id": "string", "deleted": true } ``` ## List conversion destinations `GET /ads/accounts/{adAccountId}/conversion-destinations` Where the ad account can receive conversion events (pixels, conversion actions, conversion rules, …): use id as destination_id. Access: `read` · MCP tool: `list-conversion-destinations` · Zernio: `GET /v1/accounts/{accountId}/conversion-destinations` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Query parameters - `include_inactive` (boolean) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "conversion_destination", "id": "string", "name": "string", "type": "string", "status": "string", "platform": "string", "ad_account_id": "string", "conversion_events": [ { "id": "string", "name": "string", "event_type": "string", "custom_event_name": "string", "archived": true, "optimizable": true } ], "attribution_type": "string", "post_click_attribution_window_size": 1.5, "view_through_attribution_window_size": 1.5, "value_type": "string", "value": { "currency_code": "string", "amount": "string" }, "enabled": true } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Create a conversion destination `POST /ads/accounts/{adAccountId}/conversion-destinations` LinkedIn conversion rule (not idempotent) or Google Ads conversion action (reused by name). Access: `write` · MCP tool: `create-conversion-destination` · Zernio: `POST /v1/accounts/{accountId}/conversion-destinations` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–255 characters) - `attribution_type` (string; one of LAST_TOUCH_BY_CAMPAIGN, LAST_TOUCH_BY_CONVERSION) - `post_click_attribution_window_size` (integer; one of 1, 7, 30, 90, 365) - `view_through_attribution_window_size` (integer; one of 1, 7, 30, 90, 365) - `value_type` (string; one of DYNAMIC, FIXED, NO_VALUE) - `value` (object) - `value.currency_code` (string; required; pattern ^[A-Za-z]{3}$) - `value.amount` (string | number; required) - `type` (string; required; 1–64 characters) - `auto_association_type` (string; one of ALL_CAMPAIGNS, OBJECTIVE_BASED, NONE) - `counting_type` (string; one of MANY_PER_CLICK, ONE_PER_CLICK) - `primary_for_goal` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "attribution_type": "LAST_TOUCH_BY_CAMPAIGN", "post_click_attribution_window_size": 1, "view_through_attribution_window_size": 1, "type": "string" }' ``` Response 201: ```json { "object": "conversion_destination", "id": "string", "name": "string", "type": "string", "status": "string", "platform": "string", "ad_account_id": "string", "conversion_events": [ { "id": "string", "name": "string", "event_type": "string", "custom_event_name": "string", "archived": true, "optimizable": true } ], "attribution_type": "string", "post_click_attribution_window_size": 1.5, "view_through_attribution_window_size": 1.5, "value_type": "string", "value": { "currency_code": "string", "amount": "string" }, "enabled": true } ``` ## Get a conversion destination `GET /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}` Access: `read` · MCP tool: `get-conversion-destination` · Zernio: `GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `destinationId` (string; required; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "conversion_destination", "id": "string", "name": "string", "type": "string", "status": "string", "platform": "string", "ad_account_id": "string", "conversion_events": [ { "id": "string", "name": "string", "event_type": "string", "custom_event_name": "string", "archived": true, "optimizable": true } ], "attribution_type": "string", "post_click_attribution_window_size": 1.5, "view_through_attribution_window_size": 1.5, "value_type": "string", "value": { "currency_code": "string", "amount": "string" }, "enabled": true } ``` ## Update a conversion destination `PATCH /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}` Access: `write` · MCP tool: `update-conversion-destination` · Zernio: `PATCH /v1/accounts/{accountId}/conversion-destinations/{destinationId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `destinationId` (string; required; 1–256 characters) ### Body - `name` (string; 1–255 characters) - `attribution_type` (string; one of LAST_TOUCH_BY_CAMPAIGN, LAST_TOUCH_BY_CONVERSION) - `post_click_attribution_window_size` (integer; one of 1, 7, 30, 90, 365) - `view_through_attribution_window_size` (integer; one of 1, 7, 30, 90, 365) - `value_type` (string; one of DYNAMIC, FIXED, NO_VALUE) - `value` (object) - `value.currency_code` (string; required; pattern ^[A-Za-z]{3}$) - `value.amount` (string | number; required) - `enabled` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "attribution_type": "LAST_TOUCH_BY_CAMPAIGN", "post_click_attribution_window_size": 1, "view_through_attribution_window_size": 1, "value_type": "DYNAMIC" }' ``` Response 200: ```json { "object": "conversion_destination", "id": "string", "name": "string", "type": "string", "status": "string", "platform": "string", "ad_account_id": "string", "conversion_events": [ { "id": "string", "name": "string", "event_type": "string", "custom_event_name": "string", "archived": true, "optimizable": true } ], "attribution_type": "string", "post_click_attribution_window_size": 1.5, "view_through_attribution_window_size": 1.5, "value_type": "string", "value": { "currency_code": "string", "amount": "string" }, "enabled": true } ``` ## Delete (disable) a conversion destination `DELETE /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}` Access: `write` · MCP tool: `delete-conversion-destination` · Zernio: `DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `destinationId` (string; required; 1–256 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "conversion_destination", "id": "string", "deleted": true, "state": "string" } ``` ## List associated campaigns `GET /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/associations` Access: `read` · MCP tool: `list-conversion-associations` · Zernio: `GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `destinationId` (string; required; 1–256 characters) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID/associations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "conversion_association", "campaign_id": "string", "conversion_id": "string", "associated_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com", "next_cursor": "string" } ``` ## Associate campaigns `POST /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/associations` Access: `write` · MCP tool: `add-conversion-associations` · Zernio: `POST /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `destinationId` (string; required; 1–256 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `campaign_ids` (array of string; required; 1–500 items) ```bash curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID/associations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "campaign_ids": [ "string" ] }' ``` Response 200: ```json { "object": "conversion_association_result", "succeeded": [ "string" ], "failed": [ { "campaign_id": "string", "reason": "string" } ] } ``` ## Remove associated campaigns `DELETE /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/associations` Access: `write` · MCP tool: `remove-conversion-associations` · Zernio: `DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `destinationId` (string; required; 1–256 characters) ### Query parameters - `campaign_ids` (string; required; ≤ 10000 characters): Comma separated ids ```bash curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID/associations?campaign_ids=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "conversion_association_result", "succeeded": [ "string" ], "failed": [ { "campaign_id": "string", "reason": "string" } ] } ``` ## Get attribution metrics `GET /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/metrics` Access: `read` · MCP tool: `get-conversion-metrics` · Zernio: `GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}/metrics` ### Path parameters - `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…) - `destinationId` (string; required; 1–256 characters) ### Query parameters - `start_date` (string; required; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD - `end_date` (string; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD - `granularity` (string; one of ALL, DAILY, MONTHLY, YEARLY) ```bash curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID/metrics?start_date=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "conversion_metrics", "destination_id": "string", "granularity": "string", "rows": [ { "start": "string", "end": "string", "metrics": { "external_website_conversions": 1.5, "external_website_post_click_conversions": 1.5, "external_website_post_view_conversions": 1.5, "conversion_value_in_local_currency": 1.5, "qualified_leads": 1.5, "cost_in_local_currency": 1.5 } } ] } ``` --- Source: https://socialit.com/docs/api-reference/ads-accounts-measurement/ # Platform tools API > Network-specific tools on a connected account: Google Business Profile listing, reviews, media and verification; Facebook Pages; LinkedIn organizations and mentions; Instagram stories, audio and discovery; Pinterest boards; YouTube playlists and transcripts; Reddit subreddits, flairs and votes; TikTok creator info; Discord server management; Bluesky settings. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List Google Business reviews `GET /accounts/{accountId}/gmb-reviews` Reviews of the location with average rating and total count (cursor paging, ≤50 per page). Optional location_id targets another location of the same Google login. Access: `read` · MCP tool: `list-gmb-reviews` · Zernio: `GET /v1/accounts/{accountId}/gmb-reviews` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `limit` (integer; 1–50) - `cursor` (string; ≤ 2048 characters) - `order_by` (string; one of update_time desc, updateTime desc, rating, rating desc) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-reviews" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "location_id": "string", "average_rating": 1.5, "total_review_count": 1, "data": [ { "object": "gmb_review", "id": "string", "name": "string", "location_id": "string", "rating": 1, "text": "string", "text_translated": "string", "text_original": "string", "author": "string", "author_avatar_url": "https://example.com", "author_is_anonymous": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "has_reply": true, "reply": "string", "reply_updated_at": "2026-10-13T09:00:00.000Z", "reply_state": "string", "reply_policy_violation": {}, "reply_url": "https://example.com", "has_photos": true, "photo_count": 1, "media": [ { "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com" } ] } ], "has_more": true, "next_cursor": "string" } ``` ## Batch get Google Business reviews `POST /accounts/{accountId}/gmb-reviews/batch` Reviews across up to 50 locations of the same Google account in one call. Access: `read` · MCP tool: `batch-get-gmb-reviews` · Zernio: `POST /v1/accounts/{accountId}/gmb-reviews/batch` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `location_ids` (array of string; required; 1–50 items) - `google_account_id` (string; ≤ 300 characters) - `limit` (integer; 1–50) - `cursor` (string; ≤ 2048 characters) - `order_by` (string; one of update_time desc, updateTime desc, rating, rating desc) - `ignore_rating_only_reviews` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-reviews/batch" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "location_ids": [ "string" ], "google_account_id": "string", "limit": 1, "cursor": "string", "order_by": "update_time desc" }' ``` Response 200: ```json { "object": "list", "account_id": "string", "google_account_id": "string", "data": [ { "object": "gmb_location_review", "location_id": "string", "review": { "object": "gmb_review", "id": "string", "name": "string", "location_id": "string", "rating": 1, "text": "string" } } ], "has_more": true, "next_cursor": "string" } ``` ## Get a Google Business review `GET /accounts/{accountId}/gmb-reviews/{reviewId}` Access: `read` · MCP tool: `get-gmb-review` · Zernio: `GET /v1/accounts/{accountId}/gmb-reviews/{reviewId}` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `reviewId` (string; required; 1–512 characters) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-reviews/REVIEW_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "gmb_review", "id": "string", "name": "string", "location_id": "string", "rating": 1, "text": "string", "text_translated": "string", "text_original": "string", "author": "string", "author_avatar_url": "https://example.com", "author_is_anonymous": true, "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z", "has_reply": true, "reply": "string", "reply_updated_at": "2026-10-13T09:00:00.000Z", "reply_state": "string", "reply_policy_violation": {}, "reply_url": "https://example.com", "has_photos": true, "photo_count": 1, "media": [ { "type": "string", "url": "https://example.com", "thumbnail_url": "https://example.com" } ] } ``` ## Reply to a Google Business review `POST /accounts/{accountId}/gmb-reviews/{reviewId}/reply` Creates or overwrites the owner reply (≤4096 bytes). Set automated: true for replies sent without a human pressing send (AI agents, workflows); they need the location opt-in (PATCH …/gmb-automation) and are audited. Emits review.replied. Access: `write` · MCP tool: `reply-to-gmb-review` · Zernio: `POST /v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `reviewId` (string; required; 1–512 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `comment` (string; required; 1–4096 characters) - `automated` (boolean): true when no human pressed send (AI agents, workflows, auto-responders); needs the location opt-in - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-reviews/REVIEW_ID/reply" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "comment": "string", "automated": false, "location_id": "string" }' ``` Response 200: ```json { "object": "gmb_review_reply", "review_id": "string", "name": "string", "comment": "string", "updated_at": "2026-10-13T09:00:00.000Z", "reply_state": "string", "automated": true, "deleted": true } ``` ## Delete a Google Business review reply `DELETE /accounts/{accountId}/gmb-reviews/{reviewId}/reply` Access: `write` · MCP tool: `delete-gmb-review-reply` · Zernio: `DELETE /v1/accounts/{accountId}/gmb-reviews/{reviewId}/reply` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `reviewId` (string; required; 1–512 characters) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-reviews/REVIEW_ID/reply" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "gmb_review_reply", "review_id": "string", "name": "string", "comment": "string", "updated_at": "2026-10-13T09:00:00.000Z", "reply_state": "string", "automated": true, "deleted": true } ``` ## Get the Google Business automation opt-in `GET /accounts/{accountId}/gmb-automation` Whether the business opted in to automated review replies / listing edits for the location (Google policy). Access: `read` · MCP tool: `get-gmb-automation` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-automation" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "gmb_automation", "id": "string", "account_id": "string", "location_id": "string", "automated_review_replies": true, "automated_listing_edits": true, "consent_text": "string", "opted_in_by": { "type": "string", "id": "string", "name": "string" }, "opted_in_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## Update the Google Business automation opt-in `PATCH /accounts/{accountId}/gmb-automation` Record (or revoke) the business’s express opt-in for automated review replies and listing edits on a location. Every change is written to the automation audit log. Access: `write` · MCP tool: `update-gmb-automation` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `automated_review_replies` (boolean) - `automated_listing_edits` (boolean) - `consent_text` (string | null; ≤ 2000 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-automation" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "automated_review_replies": true, "automated_listing_edits": true, "consent_text": "string" }' ``` Response 200: ```json { "object": "gmb_automation", "id": "string", "account_id": "string", "location_id": "string", "automated_review_replies": true, "automated_listing_edits": true, "consent_text": "string", "opted_in_by": { "type": "string", "id": "string", "name": "string" }, "opted_in_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } ``` ## List the Google Business automation audit log `GET /accounts/{accountId}/gmb-automation/audit-log` Opt-in changes and automated actions (automated review replies) for the account, newest first. Access: `read` · MCP tool: `list-gmb-automation-audit` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `page` (integer; ≥ 1) - `limit` (integer; 1–100) - `action` (string; one of opt_in_review_replies, opt_out_review_replies, opt_in_listing_edits, opt_out_listing_edits, automated_review_reply) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-automation/audit-log" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "gmb_automation_audit", "id": "string", "account_id": "string", "location_id": "string", "action": "string", "actor": { "type": "string", "id": "string", "name": "string" }, "details": {}, "created_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get Google Business location details `GET /accounts/{accountId}/gmb-location-details` The Business Information Location (title, address, hours, categories, profile, phone, website…) plus status flags. Optional location_id targets another location of the same Google login. Access: `read` · MCP tool: `get-gmb-location-details` · Zernio: `GET /v1/accounts/{accountId}/gmb-location-details` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `read_mask` (string; ≤ 2000 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-location-details" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "gmb_location_details", "account_id": "string", "location_id": "string", "flags": {}, "location": {}, "update_mask": [ "string" ], "validate_only": true, "warnings": [ "string" ] } ``` ## Update Google Business location details `PATCH /accounts/{accountId}/gmb-location-details` PATCH native Location fields (snake_case). update_mask is inferred from the body keys when omitted; validate_only dry-runs. Title / address / category edits may trigger re-verification (see warnings). Rate limited to 10 edits/min/location. Access: `write` · MCP tool: `update-gmb-location-details` · Zernio: `PUT /v1/accounts/{accountId}/gmb-location-details` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `update_mask` (string | array of string) - `validate_only` (boolean) - `title` (string) - `regular_hours` (object) - `special_hours` (object) - `more_hours` (array of object) - `profile` (object) - `website_uri` (string) - `phone_numbers` (object) - `categories` (object) - `service_items` (array of object) - `store_code` (string) - `labels` (array of string) - `storefront_address` (object) - `service_area` (object) - `open_info` (object) - `latlng` (object) - `ad_words_location_extensions` (object) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-location-details" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "update_mask": "string", "validate_only": true, "title": "string", "regular_hours": {} }' ``` Response 200: ```json { "object": "gmb_location_details", "account_id": "string", "location_id": "string", "flags": {}, "location": {}, "update_mask": [ "string" ], "validate_only": true, "warnings": [ "string" ] } ``` ## Get Google Business attributes `GET /accounts/{accountId}/gmb-attributes` Access: `read` · MCP tool: `get-gmb-attributes` · Zernio: `GET /v1/accounts/{accountId}/gmb-attributes` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-attributes" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "gmb_attributes", "account_id": "string", "location_id": "string", "attributes": [ {} ], "attribute_mask": [ "string" ] } ``` ## Update Google Business attributes `PATCH /accounts/{accountId}/gmb-attributes` attribute_mask defaults to the given attribute names; masked names missing from attributes are cleared. Access: `write` · MCP tool: `update-gmb-attributes` · Zernio: `PUT /v1/accounts/{accountId}/gmb-attributes` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `attributes` (array of object; required; ≤ 500 items) - `attributes[].name` (string; required; ≥ 1 characters) - `attributes[].values` (array of any) - `attributes[].repeated_enum_value` (object) - `attributes[].uri_values` (array of any) - `attribute_mask` (string | array of string) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-attributes" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "attributes": [ { "name": "string", "values": [ null ] } ], "attribute_mask": "string" }' ``` Response 200: ```json { "object": "gmb_attributes", "account_id": "string", "location_id": "string", "attributes": [ {} ], "attribute_mask": [ "string" ] } ``` ## Get Google Business attribute metadata `GET /accounts/{accountId}/gmb-attribute-metadata` Attributes available for the location, or for a category (category_name + region_code). Access: `read` · MCP tool: `get-gmb-attribute-metadata` · Zernio: `GET /v1/accounts/{accountId}/gmb-attribute-metadata` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `category_name` (string; ≤ 300 characters) - `region_code` (string; ≤ 8 characters) - `language_code` (string; ≤ 35 characters) - `show_all` (boolean) - `limit` (integer; 1–200) - `cursor` (string; ≤ 2048 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-attribute-metadata" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "location_id": "string", "data": [ {} ], "has_more": true, "next_cursor": "string" } ``` ## Get Google Business services `GET /accounts/{accountId}/gmb-services` Access: `read` · MCP tool: `get-gmb-services` · Zernio: `GET /v1/accounts/{accountId}/gmb-services` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-services" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "gmb_services", "account_id": "string", "location_id": "string", "services": [ {} ], "categories": {} } ``` ## Replace Google Business services `PATCH /accounts/{accountId}/gmb-services` Access: `write` · MCP tool: `replace-gmb-services` · Zernio: `PUT /v1/accounts/{accountId}/gmb-services` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `service_items` (array of object; required; ≤ 500 items) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-services" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "service_items": [ {} ] }' ``` Response 200: ```json { "object": "gmb_services", "account_id": "string", "location_id": "string", "services": [ {} ], "categories": {} } ``` ## Get Google Business food menus `GET /accounts/{accountId}/gmb-food-menus` Access: `read` · MCP tool: `get-gmb-food-menus` · Zernio: `GET /v1/accounts/{accountId}/gmb-food-menus` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-food-menus" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "gmb_food_menus", "account_id": "string", "location_id": "string", "name": "string", "menus": [ {} ] } ``` ## Update Google Business food menus `PATCH /accounts/{accountId}/gmb-food-menus` Access: `write` · MCP tool: `update-gmb-food-menus` · Zernio: `PUT /v1/accounts/{accountId}/gmb-food-menus` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `menus` (array of object; required) - `update_mask` (string; ≤ 500 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-food-menus" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "menus": [ {} ], "update_mask": "string" }' ``` Response 200: ```json { "object": "gmb_food_menus", "account_id": "string", "location_id": "string", "name": "string", "menus": [ {} ] } ``` ## List Google Business photos and videos `GET /accounts/{accountId}/gmb-media` Access: `read` · MCP tool: `list-gmb-media` · Zernio: `GET /v1/accounts/{accountId}/gmb-media` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `limit` (integer; 1–100) - `cursor` (string; ≤ 2048 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-media" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "location_id": "string", "total": 1, "data": [ { "object": "gmb_media", "id": "string", "name": "string", "media_format": "string", "source_url": "https://example.com", "google_url": "https://example.com", "thumbnail_url": "https://example.com", "description": "string", "create_time": "string", "location_association": {}, "dimensions": {}, "insights": {}, "attribution": {}, "warnings": [ "string" ] } ], "has_more": true, "next_cursor": "string" } ``` ## Upload a Google Business photo or video `POST /accounts/{accountId}/gmb-media` Upload by public URL (photos 10 KB–5 MB, ≥250 px; videos ≤30 s, ≤75 MB). Access: `write` · MCP tool: `upload-gmb-media` · Zernio: `POST /v1/accounts/{accountId}/gmb-media` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `source_url` (string; required; 8–4096 characters, pattern ^https?://) - `media_format` (string; one of PHOTO, VIDEO) - `category` (string; one of CATEGORY_UNSPECIFIED, COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, PRODUCT, AT_WORK, FOOD_AND_DRINK, MENU, COMMON_AREA, ROOMS, …) - `description` (string; ≤ 1000 characters) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-media" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "source_url": "https://example.com", "media_format": "PHOTO", "category": "CATEGORY_UNSPECIFIED", "description": "string" }' ``` Response 201: ```json { "object": "gmb_media", "id": "string", "name": "string", "media_format": "string", "source_url": "https://example.com", "google_url": "https://example.com", "thumbnail_url": "https://example.com", "description": "string", "create_time": "string", "location_association": {}, "dimensions": {}, "insights": {}, "attribution": {}, "warnings": [ "string" ] } ``` ## Delete a Google Business photo or video `DELETE /accounts/{accountId}/gmb-media` Access: `write` · MCP tool: `delete-gmb-media` · Zernio: `DELETE /v1/accounts/{accountId}/gmb-media` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `media_id` (string; required; 1–500 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-media?media_id=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "gmb_media", "id": "string", "name": "string", "deleted": true } ``` ## List Google Business action links `GET /accounts/{accountId}/gmb-place-actions` Access: `read` · MCP tool: `list-gmb-place-actions` · Zernio: `GET /v1/accounts/{accountId}/gmb-place-actions` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `limit` (integer; 1–100) - `cursor` (string; ≤ 2048 characters) - `filter` (string; ≤ 500 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-place-actions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "location_id": "string", "data": [ { "object": "gmb_place_action_link", "id": "string", "name": "string", "uri": "string", "place_action_type": "string", "is_preferred": true, "is_editable": true, "provider_type": "string", "create_time": "string", "update_time": "string" } ], "has_more": true, "next_cursor": "string" } ``` ## Create a Google Business action link `POST /accounts/{accountId}/gmb-place-actions` Access: `write` · MCP tool: `create-gmb-place-action` · Zernio: `POST /v1/accounts/{accountId}/gmb-place-actions` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `uri` (string; required; 8–4096 characters, pattern ^https?://) - `place_action_type` (string; required; one of APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE, SOLOPRENEUR_APPOINTMENT) - `is_preferred` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-place-actions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "uri": "xxxxxxxx", "place_action_type": "APPOINTMENT", "is_preferred": true }' ``` Response 201: ```json { "object": "gmb_place_action_link", "id": "string", "name": "string", "uri": "string", "place_action_type": "string", "is_preferred": true, "is_editable": true, "provider_type": "string", "create_time": "string", "update_time": "string" } ``` ## Update a Google Business action link `PATCH /accounts/{accountId}/gmb-place-actions` Access: `write` · MCP tool: `update-gmb-place-action` · Zernio: `PATCH /v1/accounts/{accountId}/gmb-place-actions` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `name` (string; required; 1–500 characters) - `uri` (string; 8–4096 characters, pattern ^https?://) - `place_action_type` (string; one of APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE, SOLOPRENEUR_APPOINTMENT) - `is_preferred` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-place-actions" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "name": "string", "uri": "xxxxxxxx", "place_action_type": "APPOINTMENT", "is_preferred": true }' ``` Response 200: ```json { "object": "gmb_place_action_link", "id": "string", "name": "string", "uri": "string", "place_action_type": "string", "is_preferred": true, "is_editable": true, "provider_type": "string", "create_time": "string", "update_time": "string" } ``` ## Delete a Google Business action link `DELETE /accounts/{accountId}/gmb-place-actions` Access: `write` · MCP tool: `delete-gmb-place-action` · Zernio: `DELETE /v1/accounts/{accountId}/gmb-place-actions` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `name` (string; required; 1–500 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-place-actions?name=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "gmb_place_action_link", "id": "string", "name": "string", "deleted": true } ``` ## Get Google Business verification state `GET /accounts/{accountId}/gmb-verifications` Voice of Merchant state, a summary (live, needs_verification, …) and the verifications of the location. Access: `read` · MCP tool: `get-gmb-verifications` · Zernio: `GET /v1/accounts/{accountId}/gmb-verifications` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-verifications" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "gmb_verification_state", "account_id": "string", "location_id": "string", "summary": { "status": "string", "can_edit": true, "message": "string" }, "voice_of_merchant_state": {}, "verifications": [ {} ] } ``` ## Start a Google Business verification `POST /accounts/{accountId}/gmb-verifications` Access: `write` · MCP tool: `start-gmb-verification` · Zernio: `POST /v1/accounts/{accountId}/gmb-verifications` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `method` (string; required; one of ADDRESS, EMAIL, PHONE_CALL, SMS, AUTO, TRUSTED_PARTNER, VETTED_PARTNER) - `language_code` (string; ≤ 35 characters) - `phone_number` (string; ≤ 40 characters) - `email_address` (string; ≤ 320 characters) - `mailer_contact` (object) - `context` (object) - `trusted_partner_token` (string; ≤ 2000 characters) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-verifications" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "method": "ADDRESS", "language_code": "string", "phone_number": "+15551234567", "email_address": "string" }' ``` Response 200: ```json { "object": "gmb_verification", "account_id": "string", "location_id": "string", "verification": {} } ``` ## Fetch Google Business verification options `POST /accounts/{accountId}/gmb-verifications/options` Access: `write` · MCP tool: `fetch-gmb-verification-options` · Zernio: `POST /v1/accounts/{accountId}/gmb-verifications/options` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `language_code` (string; required; 2–35 characters) - `context` (object) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-verifications/options" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "language_code": "string", "context": {} }' ``` Response 200: ```json { "object": "gmb_verification_options", "account_id": "string", "location_id": "string", "options": [ {} ] } ``` ## Complete a Google Business verification `POST /accounts/{accountId}/gmb-verifications/{verificationId}/complete` Access: `write` · MCP tool: `complete-gmb-verification` · Zernio: `POST /v1/accounts/{accountId}/gmb-verifications/{verificationId}/complete` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `verificationId` (string; required; 1–512 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `location_id` (string; 1–300 characters): Act on another location of the same Google login: locations/{id}, accounts/{a}/locations/{l} or a bare id - `pin` (string; required; 1–20 characters) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-verifications/VERIFICATION_ID/complete" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "location_id": "string", "pin": "string" }' ``` Response 200: ```json { "object": "gmb_verification", "account_id": "string", "location_id": "string", "verification": {} } ``` ## List Google Business locations of the login `GET /accounts/{accountId}/gmb-locations` Every location the connected Google login manages (location picker), with the Socialit account already connected to each. Access: `read` · MCP tool: `list-gmb-locations` · Zernio: `GET /v1/accounts/{accountId}/gmb-locations` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `search` (string; ≤ 200 characters) - `filter` (string; ≤ 500 characters) - `limit` (integer; 1–500) - `google_account_id` (string; ≤ 300 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-locations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "selected_location_id": "string", "data": [ { "object": "gmb_location", "id": "string", "location_id": "string", "external_id": "string", "name": "string", "title": "string", "google_account_id": "string", "google_account_name": "string", "google_account_type": "string", "address": "string", "category": "string", "store_code": "string", "phone": "+15551234567", "website_uri": "string", "open_status": "string", "labels": [ "string" ], "place_id": "string", "maps_uri": "string", "review_url": "https://example.com", "is_verified": true, "has_pending_edits": true, "has_google_updated": true, "can_have_food_menus": true, "can_operate_lodging_data": true, "can_operate_local_post": true, "can_modify_service_list": true, "duplicate_location": "string", "connected_account_id": "string" } ], "has_more": true, "next_cursor": "string" } ``` ## Switch the Google Business location `PATCH /accounts/{accountId}/gmb-locations` Point this account at another location of the same Google login. Emits account.updated. Access: `write` · MCP tool: `select-gmb-location` · Zernio: `PUT /v1/accounts/{accountId}/gmb-locations` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `selected_location_id` (string; required; 1–300 characters) - `google_account_id` (string; ≤ 300 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-locations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "selected_location_id": "string", "google_account_id": "string" }' ``` Response 200: ```json { "object": "gmb_location_selection", "account_id": "string", "message": "string", "selected_location": { "object": "gmb_location", "id": "string", "location_id": "string", "external_id": "string", "name": "string", "title": "string", "google_account_id": "string", "google_account_name": "string", "google_account_type": "string", "address": "string", "category": "string", "store_code": "string", "phone": "+15551234567", "website_uri": "string", "open_status": "string", "labels": [ "string" ], "place_id": "string", "maps_uri": "string", "review_url": "https://example.com", "is_verified": true, "has_pending_edits": true, "has_google_updated": true, "can_have_food_menus": true, "can_operate_lodging_data": true, "can_operate_local_post": true, "can_modify_service_list": true, "duplicate_location": "string", "connected_account_id": "string" } } ``` ## Assign a Google Business location to a profile `POST /accounts/{accountId}/gmb-locations/assign` Connect another location of the same Google login as a new account in profile_id (201), or move it there when it is already connected in this workspace (200). Counts toward the plan account allowance. Emits account.connected / account.updated. Access: `write` · MCP tool: `assign-gmb-location` · Zernio: `POST /v1/accounts/{accountId}/gmb-locations/assign` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `profile_id` (string; required; 1–80 characters) - `selected_location_id` (string; required; 1–300 characters) - `google_account_id` (string; ≤ 300 characters) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/gmb-locations/assign" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "profile_id": "string", "selected_location_id": "string", "google_account_id": "string" }' ``` Response 200: ```json { "object": "gmb_location_assignment", "message": "string", "profile_id": "string", "selected_location_id": "string", "account": { "object": "account", "id": "string", "platform": "string", "connect_flow": "string", "account_type": "string", "profile_id": "string", "group_ids": [ "string" ], "external_id": "string", "parent_external_id": "string", "username": "string", "name": "string", "display_name": "string", "avatar_url": "https://example.com", "profile_url": "https://example.com", "status": "string", "is_active": true, "needs_reconnect": true, "scopes": [ "string" ], "token_expires_at": "2026-10-13T09:00:00.000Z", "default_config": {}, "metadata": {}, "followers_count": 1, "followers_updated_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "updated_at": "2026-10-13T09:00:00.000Z" } } ``` ## List Facebook Pages of the connection `GET /accounts/{accountId}/facebook-page` Pages the connecting Facebook user granted, with the selected one and per-Page capabilities. Access: `read` · MCP tool: `list-facebook-pages` · Zernio: `GET /v1/accounts/{accountId}/facebook-page` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `refresh` (boolean) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/facebook-page" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "selected_page_id": "string", "truncated": true, "data": [ { "object": "facebook_page", "id": "string", "name": "string", "username": "string", "category": "string", "picture": "string", "tasks": [ "string" ], "can_publish": true, "can_message": true, "can_analyze": true } ], "has_more": true, "next_cursor": "string" } ``` ## Switch the Facebook Page `PATCH /accounts/{accountId}/facebook-page` Point this account at another Page the user manages (stores the Page token). Emits account.updated. Access: `write` · MCP tool: `select-facebook-page` · Zernio: `PUT /v1/accounts/{accountId}/facebook-page` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `selected_page_id` (string; required; 1–64 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/facebook-page" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "selected_page_id": "string" }' ``` Response 200: ```json { "object": "facebook_page_selection", "account_id": "string", "message": "string", "previous_page_id": "string", "selected_page": { "id": "string", "name": "string" } } ``` ## Read the Facebook Page's webhook subscription `GET /accounts/{accountId}/webhook-subscription` Whether Socialit is subscribed to the Page (real-time comments, messages, leads) and which fields are missing. Access: `read` · MCP tool: `get-facebook-webhook-subscription` · Zernio: `GET /v1/accounts/{accountId}/webhook-subscription` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/webhook-subscription" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "facebook_webhook_subscription", "account_id": "string", "page_id": "string", "app_subscribed": true, "subscribed_fields": [ "string" ], "missing_fields": [ "string" ], "leadgen": true, "apps": [ { "id": "string", "name": "string" } ], "warning": "string", "resubscribed": true } ``` ## Re-subscribe the Facebook Page to Socialit webhooks `POST /accounts/{accountId}/webhook-subscription` Access: `write` · MCP tool: `resubscribe-facebook-webhooks` · Zernio: `POST /v1/accounts/{accountId}/webhook-subscription` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `fields` (array of string; ≤ 50 items) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/webhook-subscription" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "fields": [ "string" ] }' ``` Response 200: ```json { "object": "facebook_webhook_subscription", "account_id": "string", "page_id": "string", "app_subscribed": true, "subscribed_fields": [ "string" ], "missing_fields": [ "string" ], "leadgen": true, "apps": [ { "id": "string", "name": "string" } ], "warning": "string", "resubscribed": true } ``` ## List partner businesses of the Page `GET /accounts/{accountId}/business-partners` Access: `read` · MCP tool: `list-facebook-business-partners` · Zernio: `GET /v1/accounts/{accountId}/business-partners` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/business-partners" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "page": { "id": "string", "name": "string", "business": { "id": "string", "name": "string" } }, "data": [ { "object": "facebook_business_partner", "id": "string", "name": "string", "permitted_tasks": [ "string" ] } ], "has_more": true, "next_cursor": "string" } ``` ## Share the Page with a partner business `POST /accounts/{accountId}/business-partners` Grant a partner Business Manager tasks on the Page (default ADVERTISE + ANALYZE). Access: `write` · MCP tool: `share-facebook-page-with-partner` · Zernio: `POST /v1/accounts/{accountId}/business-partners` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `business_id` (string; required; pattern ^[0-9]{1,32}$) - `permitted_tasks` (array of string; 1–40 items) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/business-partners" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "business_id": "string", "permitted_tasks": [ "string" ] }' ``` Response 200: ```json { "object": "facebook_business_partner_share", "account_id": "string", "page": { "id": "string", "name": "string", "business": { "id": "string", "name": "string" } }, "partner": { "id": "string", "permitted_tasks": [ "string" ] }, "already_shared": true } ``` ## Revoke a partner business from the Page `DELETE /accounts/{accountId}/business-partners` Access: `write` · MCP tool: `revoke-facebook-business-partner` · Zernio: `DELETE /v1/accounts/{accountId}/business-partners` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `business_id` (string; required; pattern ^[0-9]{1,32}$) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/business-partners?business_id=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "facebook_business_partner", "id": "string", "page_id": "string", "deleted": true } ``` ## List LinkedIn organizations `GET /accounts/{accountId}/linkedin-organizations` Organizations (Pages) the member has a role on, with posting/admin rights. Access: `read` · MCP tool: `list-linkedin-organizations` · Zernio: `GET /v1/accounts/{accountId}/linkedin-organizations` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/linkedin-organizations" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "data": [ { "object": "linkedin_organization", "id": "string", "urn": "string", "name": "string", "localized_name": "string", "vanity_name": "string", "logo_url": "https://example.com", "roles": [ "string" ], "can_post": true, "is_admin": true } ], "has_more": true, "next_cursor": "string" } ``` ## Switch LinkedIn account type `PATCH /accounts/{accountId}/linkedin-organization` Post as the personal profile or as an organization the member administers. Emits account.updated. Access: `write` · MCP tool: `switch-linkedin-account-type` · Zernio: `PUT /v1/accounts/{accountId}/linkedin-organization` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `account_type` (string; required; one of personal, organization) - `selected_organization` (string | object) - one of: Option 1 (string) - one of: Option 2 (object) - `selected_organization.id` (string | integer) - `selected_organization.urn` (string) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/linkedin-organization" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "account_type": "personal", "selected_organization": "string" }' ``` Response 200: ```json { "object": "linkedin_account_type", "account_id": "string", "account_type": "string", "account_name": "string", "message": "string" } ``` ## Resolve a LinkedIn mention `GET /accounts/{accountId}/linkedin-mentions` Turn a linkedin.com profile/company URL (or URN) into a mention (@[Name](urn)) for post content. Access: `read` · MCP tool: `resolve-linkedin-mention` · Zernio: `GET /v1/accounts/{accountId}/linkedin-mentions` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `url` (string; required; 3–2000 characters) - `display_name` (string; ≤ 200 characters) - `organization_urn` (string; ≤ 200 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/linkedin-mentions?url=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "linkedin_mention", "urn": "string", "type": "string", "display_name": "string", "mention_format": "string", "vanity_name": "string", "warning": "string" } ``` ## List active Instagram stories `GET /accounts/{accountId}/instagram/stories` Access: `read` · MCP tool: `list-instagram-stories` · Zernio: `GET /v1/accounts/{accountId}/instagram/stories` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `limit` (integer; 1–100) - `cursor` (string; ≤ 2048 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram/stories" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "data": [ { "object": "instagram_story", "id": "string", "media_type": "string", "media_product_type": "string", "media_url": "https://example.com", "thumbnail_url": "https://example.com", "permalink": "string", "timestamp": "string" } ], "has_more": true, "next_cursor": "string" } ``` ## Get Instagram story insights `GET /accounts/{accountId}/instagram/stories/{storyId}/insights` Metrics of a live story (24 h). source: unavailable with reason when Instagram no longer serves them. Access: `read` · MCP tool: `get-instagram-story-insights` · Zernio: `GET /v1/accounts/{accountId}/instagram/stories/{storyId}/insights` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `storyId` (string; required; 1–128 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram/stories/STORY_ID/insights" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "instagram_story_insights", "story_id": "string", "source": "string", "reason": "string", "views": 1, "reach": 1, "replies": 1, "shares": 1, "profile_visits": 1, "follows": 1, "total_interactions": 1, "navigation": 1, "taps_forward": 1, "taps_back": 1, "exits": 1, "swipes_forward": 1 } ``` ## Get Instagram publishing limit `GET /accounts/{accountId}/instagram/publishing-limit` Rolling 24 h content publishing quota (usage, total, remaining). Access: `read` · MCP tool: `get-instagram-publishing-limit` · Zernio: `GET /v1/accounts/{accountId}/instagram/publishing-limit` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram/publishing-limit" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "instagram_publishing_limit", "account_id": "string", "quota_usage": 1, "quota_total": 1, "quota_duration_seconds": 1, "remaining": 1 } ``` ## Search Instagram audio `GET /accounts/{accountId}/instagram/audio` Reels audio search (trending when q is omitted). Needs a Facebook-Login Instagram connection. Access: `read` · MCP tool: `search-instagram-audio` · Zernio: `GET /v1/accounts/{accountId}/instagram/audio` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `audio_type` (string; one of music, original_sound) - `q` (string; ≤ 200 characters) - `limit` (integer; 1–100) - `cursor` (string; ≤ 2048 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram/audio" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "data": [ { "object": "instagram_audio", "audio_id": "string", "title": "string", "duration_in_ms": 1, "audio_type": "string", "display_artist": "string", "ig_username": "string", "profile_picture_url": "https://example.com", "download_url": "https://example.com", "preview_url": "https://example.com", "cover_artwork_url": "https://example.com", "is_ads_eligible": true } ], "has_more": true, "next_cursor": "string" } ``` ## Get Instagram audio metadata `GET /accounts/{accountId}/instagram/audio/{audioId}` Re-validates a track and refreshes its preview URL (expires after ~1.5 days). Access: `read` · MCP tool: `get-instagram-audio` · Zernio: `GET /v1/accounts/{accountId}/instagram/audio/{audioId}` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `audioId` (string; required; 1–128 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram/audio/AUDIO_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "instagram_audio", "audio_id": "string", "title": "string", "duration_in_ms": 1, "audio_type": "string", "display_artist": "string", "ig_username": "string", "profile_picture_url": "https://example.com", "download_url": "https://example.com", "preview_url": "https://example.com", "cover_artwork_url": "https://example.com", "is_ads_eligible": true } ``` ## Look up a public Instagram Business account `GET /accounts/{accountId}/instagram/business-discovery` Public profile and recent media of another Business/Creator account (competitor research). Access: `read` · MCP tool: `instagram-business-discovery` · Zernio: `GET /v1/accounts/{accountId}/instagram/business-discovery` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `username` (string; required; pattern ^@?[A-Za-z0-9._]{1,30}$) - `limit` (integer; 1–50) - `cursor` (string; ≤ 2048 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram/business-discovery?username=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "instagram_business_discovery", "profile": { "id": "string", "ig_id": 1, "username": "string", "name": "string", "biography": "string", "website": "https://example.com", "profile_picture_url": "https://example.com", "followers_count": 1, "follows_count": 1, "media_count": 1 }, "media": [ {} ], "next_cursor": "string" } ``` ## Check whether an Instagram user follows the account `GET /accounts/{accountId}/follow-status/{userId}` Follow relationship for an Instagram-scoped user id (IGSID). Meta only answers for users who messaged the account; otherwise unavailable_reason is set. Access: `read` · MCP tool: `get-instagram-follow-status` · Zernio: `GET /v1/accounts/{accountId}/follow-status/{userId}` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `userId` (string; required; 1–128 characters) ### Query parameters - `refresh` (boolean) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/follow-status/USER_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "instagram_follow_status", "account_id": "string", "user_id": "string", "is_follower": true, "is_followed_by_account": true, "follower_count": 1, "is_verified": true, "username": "string", "name": "string", "unavailable_reason": "string" } ``` ## List Pinterest boards `GET /accounts/{accountId}/pinterest-boards` Every board of the Pinterest account plus the stored default board. Access: `read` · MCP tool: `list-pinterest-boards` · Zernio: `GET /v1/accounts/{accountId}/pinterest-boards` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pinterest-boards" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "default_board_id": "string", "default_board_name": "string", "data": [ { "object": "pinterest_board", "id": "string", "name": "string", "description": "string", "privacy": "string", "url": "https://example.com", "pin_count": 1, "follower_count": 1, "collaborator_count": 1, "is_ads_only": true, "image_cover_url": "https://example.com", "owner_username": "string", "created_at": "2026-10-13T09:00:00.000Z", "board_pins_modified_at": "2026-10-13T09:00:00.000Z" } ], "has_more": true, "next_cursor": "string" } ``` ## Create a Pinterest board `POST /accounts/{accountId}/pinterest-boards` SECRET boards need the boards:write_secret scope. Access: `write` · MCP tool: `create-pinterest-board` · Zernio: `POST /v1/accounts/{accountId}/pinterest-boards` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–180 characters) - `description` (string; ≤ 500 characters) - `privacy` (string; one of PUBLIC, PROTECTED, SECRET) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pinterest-boards" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "description": "string", "privacy": "PUBLIC" }' ``` Response 201: ```json { "object": "pinterest_board", "id": "string", "name": "string", "description": "string", "privacy": "string", "url": "https://example.com", "pin_count": 1, "follower_count": 1, "collaborator_count": 1, "is_ads_only": true, "image_cover_url": "https://example.com", "owner_username": "string", "created_at": "2026-10-13T09:00:00.000Z", "board_pins_modified_at": "2026-10-13T09:00:00.000Z" } ``` ## Set the default Pinterest board `PATCH /accounts/{accountId}/pinterest-boards` Used when a post does not name a board. Emits account.updated. Access: `write` · MCP tool: `set-default-pinterest-board` · Zernio: `PUT /v1/accounts/{accountId}/pinterest-boards` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `default_board_id` (string; required; 1–64 characters) - `default_board_name` (string; ≤ 180 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pinterest-boards" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "default_board_id": "string", "default_board_name": "string" }' ``` Response 200: ```json { "object": "pinterest_default_board", "account_id": "string", "default_board_id": "string", "default_board_name": "string", "message": "string" } ``` ## List YouTube playlists `GET /accounts/{accountId}/youtube-playlists` Every playlist of the channel plus the stored default playlist. Access: `read` · MCP tool: `list-youtube-playlists` · Zernio: `GET /v1/accounts/{accountId}/youtube-playlists` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/youtube-playlists" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "default_playlist_id": "string", "default_playlist_name": "string", "data": [ { "object": "youtube_playlist", "id": "string", "title": "string", "description": "string", "privacy": "string", "item_count": 1, "thumbnail_url": "https://example.com", "published_at": "2026-10-13T09:00:00.000Z", "url": "https://example.com" } ], "has_more": true, "next_cursor": "string" } ``` ## Create a YouTube playlist `POST /accounts/{accountId}/youtube-playlists` Costs 50 quota units; not idempotent upstream (list before retrying). Access: `write` · MCP tool: `create-youtube-playlist` · Zernio: `POST /v1/accounts/{accountId}/youtube-playlists` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `title` (string; required; 1–150 characters) - `description` (string; ≤ 5000 characters) - `privacy` (string; one of private, public, unlisted) - `default_language` (string; ≤ 35 characters) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/youtube-playlists" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "title": "string", "description": "string", "privacy": "private", "default_language": "string" }' ``` Response 201: ```json { "object": "youtube_playlist", "id": "string", "title": "string", "description": "string", "privacy": "string", "item_count": 1, "thumbnail_url": "https://example.com", "published_at": "2026-10-13T09:00:00.000Z", "url": "https://example.com" } ``` ## Set the default YouTube playlist `PATCH /accounts/{accountId}/youtube-playlists` Pre-fills the composer playlist. Emits account.updated. Access: `write` · MCP tool: `set-default-youtube-playlist` · Zernio: `PUT /v1/accounts/{accountId}/youtube-playlists` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `default_playlist_id` (string; required; 1–64 characters) - `default_playlist_name` (string; ≤ 150 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/youtube-playlists" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "default_playlist_id": "string", "default_playlist_name": "string" }' ``` Response 200: ```json { "object": "youtube_default_playlist", "account_id": "string", "default_playlist_id": "string", "default_playlist_name": "string" } ``` ## Get a YouTube video transcript `GET /accounts/{accountId}/youtube-captions` Caption track of a video on the channel as text + timed cues (optionally SRT/VTT, or translated with tlang). Access: `read` · MCP tool: `get-youtube-transcript` · Zernio: `GET /v1/accounts/{accountId}/youtube-captions` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `video_id` (string; required; 1–64 characters) - `language` (string; ≤ 35 characters) - `format` (string; one of json, srt, vtt) - `track_id` (string; ≤ 200 characters) - `tlang` (string; ≤ 35 characters) - `refresh` (boolean) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/youtube-captions?video_id=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "youtube_transcript", "account_id": "string", "video_id": "string", "language": "en", "track_id": "string", "track_kind": "string", "source": "string", "fetched_at": "2026-10-13T09:00:00.000Z", "text": "string", "cues": [ { "start": 1.5, "end": 1.5, "text": "string" } ], "srt": "string", "vtt": "string", "available_tracks": [ {} ] } ``` ## List Reddit subreddits `GET /accounts/{accountId}/reddit-subreddits` Subreddits the user can post to (subscriber/contributor/moderator, plus the user profile) and the default subreddit. Access: `read` · MCP tool: `list-reddit-subreddits` · Zernio: `GET /v1/accounts/{accountId}/reddit-subreddits` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `where` (string; one of postable, subscriber, moderator, contributor) - `limit` (integer; 1–100) - `cursor` (string; ≤ 200 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reddit-subreddits" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "default_subreddit": "string", "data": [ { "object": "reddit_subreddit", "id": "string", "name": "string", "prefixed_name": "string", "title": "string", "description": "string", "subscribers": 1, "active_users": 1, "type": "string", "over_18": true, "quarantined": true, "submission_type": "string", "post_types": {}, "user_is_moderator": true, "user_is_contributor": true, "user_is_subscriber": true } ], "has_more": true, "next_cursor": "string" } ``` ## Set the default subreddit `PATCH /accounts/{accountId}/reddit-subreddits` Validates the subreddit exists. Emits account.updated. Access: `write` · MCP tool: `set-default-reddit-subreddit` · Zernio: `PUT /v1/accounts/{accountId}/reddit-subreddits` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `default_subreddit` (string; required; 1–64 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reddit-subreddits" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "default_subreddit": "string" }' ``` Response 200: ```json { "object": "reddit_default_subreddit", "account_id": "string", "default_subreddit": "string" } ``` ## Get subreddit rules `GET /accounts/{accountId}/reddit-subreddits/{subreddit}/rules` Access: `read` · MCP tool: `get-reddit-subreddit-rules` · Zernio: `GET /v1/accounts/{accountId}/reddit-subreddits/{subreddit}/rules` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `subreddit` (string; required; 1–64 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reddit-subreddits/SUBREDDIT/rules" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "reddit_subreddit_rules", "subreddit": "string", "rules": [ { "id": "string", "priority": 1, "short_name": "string", "description": "string", "violation_reason": "string", "kind": "string", "created_at": "2026-10-13T09:00:00.000Z" } ], "site_rules": [ "string" ], "site_rules_flow": [ {} ] } ``` ## List subreddit post flairs `GET /accounts/{accountId}/reddit-flairs` restricted: true when the user cannot set link flair in that subreddit. Access: `read` · MCP tool: `list-reddit-flairs` · Zernio: `GET /v1/accounts/{accountId}/reddit-flairs` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `subreddit` (string; required; 1–64 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reddit-flairs?subreddit=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "subreddit": "string", "restricted": true, "data": [ { "object": "reddit_flair", "id": "string", "text": "string", "text_color": "string", "background_color": "string", "text_editable": true, "type": "string", "richtext": [ null ], "mod_only": true, "allowable_content": "string", "max_emojis": 1, "css_class": "string" } ], "has_more": true, "next_cursor": "string" } ``` ## Set a Reddit post flair `POST /accounts/{accountId}/reddit-flairs` Access: `write` · MCP tool: `set-reddit-post-flair` · Zernio: `POST /v1/accounts/{accountId}/reddit-flairs` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `subreddit` (string; 1–64 characters) - `post_id` (string; required; 1–32 characters) - `flair_template_id` (string; required; 1–64 characters) - `text` (string; ≤ 64 characters) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reddit-flairs" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "subreddit": "string", "post_id": "string", "flair_template_id": "string", "text": "string" }' ``` Response 200: ```json { "object": "reddit_post_flair", "account_id": "string", "post_id": "string", "flair_template_id": "string", "text": "string", "success": true } ``` ## Vote on a Reddit post or comment `POST /accounts/{accountId}/reddit-vote` One vote per call, triggered by an explicit human action (automated or bulk voting violates Reddit rules). Access: `write` · MCP tool: `vote-on-reddit` · Zernio: `POST /v1/accounts/{accountId}/reddit-vote` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `thing_id` (string; required; 2–32 characters) - `direction` (integer; required; one of 1, 0, -1) ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/reddit-vote" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "thing_id": "string", "direction": 1 }' ``` Response 200: ```json { "object": "reddit_vote", "account_id": "string", "thing_id": "string", "direction": 1, "success": true } ``` ## Get TikTok creator info `GET /accounts/{accountId}/tiktok/creator-info` Latest creator_info for the Post-to-TikTok UX: privacy options, interaction locks, max duration, whether the creator can post now. Access: `read` · MCP tool: `get-tiktok-creator-info` · Zernio: `GET /v1/accounts/{accountId}/tiktok/creator-info` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `media_type` (string; one of video, photo) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tiktok/creator-info" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "tiktok_creator_info", "account_id": "string", "lane": "string", "creator": { "nickname": "string", "username": "string", "avatar_url": "https://example.com", "is_verified": true, "can_post_more": true, "reason": "string" }, "privacy_levels": [ { "value": "string", "label": "string" } ], "posting_limits": { "max_video_duration_sec": 1, "interaction_settings": { "allow_comment": { "enabled": true, "required": true, "default": true, "label": "string" }, "allow_duet": { "enabled": true, "required": true, "default": true, "label": "string" }, "allow_stitch": { "enabled": true, "required": true, "default": true, "label": "string" } } }, "commercial_content_types": [ { "value": "string", "label": "string", "requires": "string" } ], "warning": "string" } ``` ## Get TikTok composer requirements `GET /accounts/{accountId}/tiktok/composer` Everything a "Post to TikTok" UI must render under the Content Sharing Guidelines, from live creator_info: creator nickname/avatar, privacy options (no default), interaction toggles (off by default, locked when the creator disabled them), commercial content disclosure, the exact declaration text, notices and limits. Re-fetch on every composer render. Access: `read` · MCP tool: `get-tiktok-composer-requirements` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `media_type` (string; one of video, photo) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tiktok/composer" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "tiktok_composer_requirements", "account_id": "string", "lane": "string", "media_type": "string", "fetched_at": "2026-10-13T09:00:00.000Z", "creator": { "nickname": "string", "username": "string", "avatar_url": "https://example.com", "avatar_ttl_seconds": 1, "must_display": [ "string" ], "can_post": true, "cannot_post_reason": "string", "cannot_post_message": "string", "warning": "string" }, "privacy": { "options": [ { "value": "string", "label": "string", "allowed_with_branded_content": true } ], "default": "string", "required": true, "control": "string", "direct_post_forced": "string" }, "interactions": { "comment": { "label": "string", "available": true, "disabled_by_creator": true, "default": true, "required_user_action": true }, "duet": { "label": "string", "available": true, "disabled_by_creator": true, "default": true, "required_user_action": true }, "stitch": { "label": "string", "available": true, "disabled_by_creator": true, "default": true, "required_user_action": true } }, "max_video_duration_sec": 1, "commercial_content": { "toggle": { "label": "string", "default": true }, "options": [ { "value": "string", "label": "string", "maps_to": "+15551234567", "notice": "string", "default": true, "disallowed_privacy": [ "string" ] } ], "multi_select": true, "both_selected_notice": "string", "selection_required_when_on": true, "publish_disabled_tooltip": "string" }, "declaration": { "position": "string", "default": "string", "your_brand_only": "string", "branded_content": "string", "links": { "musicUsageConfirmation": "string", "brandedContentPolicy": "string" } }, "notices": { "processing": "string", "draft": "string" }, "rules": { "key": true }, "limits": { "title_max": 1, "description_max": 1, "photos_max": 1, "formats": [ "string" ], "max_bytes": 1, "posts_per_day": 1, "pending_drafts": 1 }, "features": { "key": true } } ``` ## List trending TikTok commercial music `GET /accounts/{accountId}/tiktok/commercial-music` Commercial Music Library tracks (TikTok Business connections). Access: `read` · MCP tool: `list-tiktok-commercial-music` · Zernio: `GET /v1/accounts/{accountId}/tiktok/commercial-music` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `country_code` (string; pattern ^[A-Za-z]{2}$) - `genre` (string; ≤ 64 characters) - `date_range` (string; one of 1DAY, 7DAY, 30DAY, 90DAY) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tiktok/commercial-music" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "data": [ { "object": "tiktok_music_track", "id": "string", "commercial_music_id": "string", "name": "string", "artist": "string", "duration_sec": 1.5, "genres": [ "string" ], "preview_url": "https://example.com", "thumbnail_url": "https://example.com", "rank": 1, "trending_history": [ {} ], "clip": { "id": "string", "duration_sec": 1.5, "preview_url": "https://example.com" } } ], "has_more": true, "next_cursor": "string" } ``` ## Search TikTok location tags `GET /accounts/{accountId}/tiktok/locations` Up to 20 location tags for posts (TikTok Business connections). Access: `read` · MCP tool: `search-tiktok-locations` · Zernio: `GET /v1/accounts/{accountId}/tiktok/locations` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `query` (string; required; 1–100 characters) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tiktok/locations?query=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "data": [ { "object": "tiktok_location", "id": "string", "name": "string", "address": "string" } ], "has_more": true, "next_cursor": "string" } ``` ## Get Bluesky account settings `GET /accounts/{accountId}/bluesky-settings` Posting defaults applied to every new Bluesky post (languages, reply/quote controls, labels, tags, auto facets/link cards). Access: `read` · MCP tool: `get-bluesky-settings` · Zernio: `GET /v1/accounts/{accountId}/bluesky-settings` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/bluesky-settings" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "bluesky_settings", "account_id": "string", "default_langs": [ "string" ], "default_threadgate": [ "string" ], "default_postgate": { "disable_quotes": true }, "default_labels": [ "string" ], "default_tags": [ "string" ], "auto_facets": true, "auto_link_cards": true } ``` ## Update Bluesky account settings `PATCH /accounts/{accountId}/bluesky-settings` Partial update; only affects posts published afterwards. Emits account.updated. Access: `write` · MCP tool: `update-bluesky-settings` · Zernio: `PATCH /v1/accounts/{accountId}/bluesky-settings` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `default_langs` (array of string | null; ≤ 3 items) - `default_threadgate` (array of string | null; ≤ 5 items) - `default_postgate` (object | null) - `default_postgate.disable_quotes` (boolean) - `default_labels` (array of string; ≤ 4 items) - `default_tags` (array of string; ≤ 8 items) - `auto_facets` (boolean) - `auto_link_cards` (boolean) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/bluesky-settings" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "default_langs": [ "string" ], "default_threadgate": [ "string" ], "default_postgate": { "disable_quotes": true }, "default_labels": [ "sexual" ], "default_tags": [ "string" ] }' ``` Response 200: ```json { "object": "bluesky_settings", "account_id": "string", "default_langs": [ "string" ], "default_threadgate": [ "string" ], "default_postgate": { "disable_quotes": true }, "default_labels": [ "string" ], "default_tags": [ "string" ], "auto_facets": true, "auto_link_cards": true } ``` ## Get Discord account settings `GET /accounts/{accountId}/discord-settings` Access: `read` · MCP tool: `get-discord-settings` · Zernio: `GET /v1/accounts/{accountId}/discord-settings` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/discord-settings" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "discord_settings", "account_id": "string", "mode": "string", "guild_id": "string", "guild_name": "string", "channel_id": "string", "channel_name": "string", "channel_type": 1, "webhook_username": "string", "webhook_avatar_url": "https://example.com" } ``` ## Update Discord account settings `PATCH /accounts/{accountId}/discord-settings` Webhook identity (username / avatar; empty clears) or, for bot connections, the posting channel in the same server. Emits account.updated. Access: `write` · MCP tool: `update-discord-settings` · Zernio: `PATCH /v1/accounts/{accountId}/discord-settings` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `webhook_username` (string | null; ≤ 80 characters) - `webhook_avatar_url` (string | null; ≤ 2048 characters) - `channel_id` (string; pattern ^[0-9]{5,25}$) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/discord-settings" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "webhook_username": "string", "webhook_avatar_url": "https://example.com", "channel_id": "string" }' ``` Response 200: ```json { "object": "discord_settings", "account_id": "string", "mode": "string", "guild_id": "string", "guild_name": "string", "channel_id": "string", "channel_name": "string", "channel_type": 1, "webhook_username": "string", "webhook_avatar_url": "https://example.com" } ``` ## List Discord server channels `GET /accounts/{accountId}/discord-channels` Access: `read` · MCP tool: `list-discord-channels` · Zernio: `GET /v1/accounts/{accountId}/discord-channels` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ### Query parameters - `types` (string; pattern ^[0-9]+(,[0-9]+)*$) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/discord-channels" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "data": [ { "object": "discord_channel", "id": "string", "name": "string", "type": 1, "type_name": "string", "parent_id": "string", "position": 1, "topic": "string", "nsfw": true, "postable": true } ], "has_more": true, "next_cursor": "string" } ``` ## Send a Discord direct message `POST /discord/dms` DM a server member from the Socialit bot. Runs on the Socialit Discord bot; account_id must be a bot-mode Discord account connected to that server. Access: `write` · MCP tool: `send-discord-dm` · Zernio: `POST /v1/discord/dms` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `user_id` (string; required; pattern ^[0-9]{5,25}$) - `content` (string; ≤ 2000 characters) - `embeds` (array of object; ≤ 10 items) - `attachments` (array of object; ≤ 10 items) - `attachments[].type` (string; required; one of image, video, gif, document) - `attachments[].url` (string; required; ≤ 4096 characters, pattern ^https?://) - `attachments[].filename` (string; ≤ 200 characters) - `attachments[].mime_type` (string; ≤ 100 characters) - `attachments[].size` (integer) - `tts` (boolean) ```bash curl -X POST "https://api.socialit.com/v1/discord/dms" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "user_id": "string", "content": "string", "embeds": [ {} ], "attachments": [ { "type": "image", "url": "https://example.com" } ] }' ``` Response 200: ```json { "object": "discord_dm", "account_id": "string", "message_id": "string", "channel_id": "string", "url": "https://example.com", "timestamp": "string", "recipient": { "user_id": "string", "platform": "string" } } ``` ## List Discord server roles `GET /discord/guilds/{guildId}/roles` Runs on the Socialit Discord bot; account_id must be a bot-mode Discord account connected to that server. Access: `read` · MCP tool: `list-discord-roles` · Zernio: `GET /v1/discord/guilds/{guildId}/roles` ### Path parameters - `guildId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/discord/guilds/GUILD_ID/roles?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "guild_id": "string", "data": [ { "object": "discord_role", "id": "string", "name": "string", "color": 1, "position": 1, "permissions": "string", "permission_names": [ "string" ], "managed": true, "mentionable": true, "hoist": true, "icon": "string", "unicode_emoji": "string" } ], "has_more": true, "next_cursor": "string" } ``` ## Create a Discord server role `POST /discord/guilds/{guildId}/roles` Runs on the Socialit Discord bot; account_id must be a bot-mode Discord account connected to that server. Needs MANAGE_ROLES. Access: `write` · MCP tool: `create-discord-role` · Zernio: `POST /v1/discord/guilds/{guildId}/roles` ### Path parameters - `guildId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–100 characters) - `color` (integer | string) - `hoist` (boolean) - `mentionable` (boolean) - `permissions` (string | array of string) - `unicode_emoji` (string | null; ≤ 32 characters) - `reason` (string; ≤ 512 characters) ```bash curl -X POST "https://api.socialit.com/v1/discord/guilds/GUILD_ID/roles?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "color": 0, "hoist": true, "mentionable": true, "permissions": "string" }' ``` Response 201: ```json { "object": "discord_role", "id": "string", "name": "string", "color": 1, "position": 1, "permissions": "string", "permission_names": [ "string" ], "managed": true, "mentionable": true, "hoist": true, "icon": "string", "unicode_emoji": "string" } ``` ## Edit a Discord server role `PATCH /discord/guilds/{guildId}/roles/{roleId}` Access: `write` · MCP tool: `update-discord-role` · Zernio: `PATCH /v1/discord/guilds/{guildId}/roles/{roleId}` ### Path parameters - `guildId` (string; required; 1–512 characters) - `roleId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) ### Body - `name` (string; 1–100 characters) - `color` (integer | string) - `hoist` (boolean) - `mentionable` (boolean) - `permissions` (string | array of string) - `unicode_emoji` (string | null; ≤ 32 characters) - `reason` (string; ≤ 512 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/discord/guilds/GUILD_ID/roles/ROLE_ID?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "color": 0, "hoist": true, "mentionable": true, "permissions": "string" }' ``` Response 200: ```json { "object": "discord_role", "id": "string", "name": "string", "color": 1, "position": 1, "permissions": "string", "permission_names": [ "string" ], "managed": true, "mentionable": true, "hoist": true, "icon": "string", "unicode_emoji": "string" } ``` ## Delete a Discord server role `DELETE /discord/guilds/{guildId}/roles/{roleId}` Access: `write` · MCP tool: `delete-discord-role` · Zernio: `DELETE /v1/discord/guilds/{guildId}/roles/{roleId}` ### Path parameters - `guildId` (string; required; 1–512 characters) - `roleId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `reason` (string; ≤ 512 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/discord/guilds/GUILD_ID/roles/ROLE_ID?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "discord_role", "id": "string", "deleted": true } ``` ## List Discord server members `GET /discord/guilds/{guildId}/members` Needs the privileged GUILD_MEMBERS intent; otherwise an empty list with intent_missing: true. Page with after = next_cursor. Access: `read` · MCP tool: `list-discord-members` · Zernio: `GET /v1/discord/guilds/{guildId}/members` ### Path parameters - `guildId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `limit` (integer; 1–1000) - `after` (string; pattern ^[0-9]{5,25}$) ```bash curl "https://api.socialit.com/v1/discord/guilds/GUILD_ID/members?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "guild_id": "string", "intent_missing": true, "data": [ { "object": "discord_member", "id": "string", "username": "string", "global_name": "string", "nick": "string", "display_name": "string", "avatar": "string", "bot": true, "roles": [ "string" ], "joined_at": "2026-10-13T09:00:00.000Z", "premium_since": "string", "pending": true, "communication_disabled_until": "string", "flags": 1 } ], "has_more": true, "next_cursor": "string" } ``` ## Search Discord server members `GET /discord/guilds/{guildId}/members/search` Prefix match on username / nickname (no privileged intent needed). Access: `read` · MCP tool: `search-discord-members` · Zernio: `GET /v1/discord/guilds/{guildId}/members/search` ### Path parameters - `guildId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `query` (string; required; 1–100 characters) - `limit` (integer; 1–1000) ```bash curl "https://api.socialit.com/v1/discord/guilds/GUILD_ID/members/search?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd&query=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "guild_id": "string", "intent_missing": true, "data": [ { "object": "discord_member", "id": "string", "username": "string", "global_name": "string", "nick": "string", "display_name": "string", "avatar": "string", "bot": true, "roles": [ "string" ], "joined_at": "2026-10-13T09:00:00.000Z", "premium_since": "string", "pending": true, "communication_disabled_until": "string", "flags": 1 } ], "has_more": true, "next_cursor": "string" } ``` ## Get a Discord server member `GET /discord/guilds/{guildId}/members/{userId}` Access: `read` · MCP tool: `get-discord-member` · Zernio: `GET /v1/discord/guilds/{guildId}/members/{userId}` ### Path parameters - `guildId` (string; required; 1–512 characters) - `userId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/discord/guilds/GUILD_ID/members/USER_ID?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "discord_member", "id": "string", "username": "string", "global_name": "string", "nick": "string", "display_name": "string", "avatar": "string", "bot": true, "roles": [ "string" ], "joined_at": "2026-10-13T09:00:00.000Z", "premium_since": "string", "pending": true, "communication_disabled_until": "string", "flags": 1 } ``` ## Assign a role to a Discord member `PUT /discord/guilds/{guildId}/members/{userId}/roles/{roleId}` Access: `write` · MCP tool: `add-discord-member-role` · Zernio: `PUT /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}` ### Path parameters - `guildId` (string; required; 1–512 characters) - `userId` (string; required; 1–512 characters) - `roleId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `reason` (string; ≤ 512 characters) ```bash curl -X PUT "https://api.socialit.com/v1/discord/guilds/GUILD_ID/members/USER_ID/roles/ROLE_ID?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "discord_member_role", "guild_id": "string", "user_id": "string", "role_id": "string", "operation": "string" } ``` ## Remove a role from a Discord member `DELETE /discord/guilds/{guildId}/members/{userId}/roles/{roleId}` Access: `write` · MCP tool: `remove-discord-member-role` · Zernio: `DELETE /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}` ### Path parameters - `guildId` (string; required; 1–512 characters) - `userId` (string; required; 1–512 characters) - `roleId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `reason` (string; ≤ 512 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/discord/guilds/GUILD_ID/members/USER_ID/roles/ROLE_ID?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "discord_member_role", "guild_id": "string", "user_id": "string", "role_id": "string", "operation": "string" } ``` ## Delete a Discord channel message `DELETE /discord/channels/{channelId}/messages/{messageId}` Runs on the Socialit Discord bot; account_id must be a bot-mode Discord account connected to that server. Deleting other users' messages needs MANAGE_MESSAGES. Access: `write` · MCP tool: `delete-discord-message` · Zernio: `DELETE /v1/discord/channels/{channelId}/messages/{messageId}` ### Path parameters - `channelId` (string; required; 1–512 characters) - `messageId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `reason` (string; ≤ 512 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/discord/channels/CHANNEL_ID/messages/MESSAGE_ID?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "discord_message", "id": "string", "channel_id": "string", "deleted": true } ``` ## Crosspost a Discord announcement `POST /discord/channels/{channelId}/messages/{messageId}/crosspost` Publish an announcement-channel message to every following server. Access: `write` · MCP tool: `crosspost-discord-message` · Zernio: `POST /v1/discord/channels/{channelId}/messages/{messageId}/crosspost` ### Path parameters - `channelId` (string; required; 1–512 characters) - `messageId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/discord/channels/CHANNEL_ID/messages/MESSAGE_ID/crosspost?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` Response 200: ```json { "object": "discord_crosspost", "id": "string", "channel_id": "string", "message": {} } ``` ## Create a Discord public thread `POST /discord/channels/{channelId}/threads` From a message when message_id is set, otherwise a standalone thread. Access: `write` · MCP tool: `create-discord-thread` · Zernio: `POST /v1/discord/channels/{channelId}/threads` ### Path parameters - `channelId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `name` (string; required; 1–100 characters) - `message_id` (string; pattern ^[0-9]{5,25}$) - `auto_archive_duration` (integer; one of 60, 1440, 4320, 10080) - `rate_limit_per_user` (integer; 0–21600) - `reason` (string; ≤ 512 characters) ```bash curl -X POST "https://api.socialit.com/v1/discord/channels/CHANNEL_ID/threads?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "message_id": "string", "auto_archive_duration": 60, "rate_limit_per_user": 0, "reason": "string" }' ``` Response 201: ```json { "object": "discord_thread", "id": "string", "name": "string", "parent_id": "string", "thread": {} } ``` ## List pinned Discord messages `GET /discord/channels/{channelId}/pins` Access: `read` · MCP tool: `list-discord-pins` · Zernio: `GET /v1/discord/channels/{channelId}/pins` ### Path parameters - `channelId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `before` (string; ≤ 40 characters) - `limit` (integer; 1–50) ```bash curl "https://api.socialit.com/v1/discord/channels/CHANNEL_ID/pins?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "channel_id": "string", "data": [ { "object": "discord_pinned_message", "id": "string", "channel_id": "string", "content": "string", "timestamp": "string", "pinned_at": "2026-10-13T09:00:00.000Z", "author": {}, "attachments": [ {} ], "embeds": [ {} ] } ], "has_more": true, "next_cursor": "string" } ``` ## Pin a Discord message `PUT /discord/channels/{channelId}/pins/{messageId}` Access: `write` · MCP tool: `pin-discord-message` · Zernio: `PUT /v1/discord/channels/{channelId}/pins/{messageId}` ### Path parameters - `channelId` (string; required; 1–512 characters) - `messageId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `reason` (string; ≤ 512 characters) ```bash curl -X PUT "https://api.socialit.com/v1/discord/channels/CHANNEL_ID/pins/MESSAGE_ID?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "discord_pin", "channel_id": "string", "message_id": "string", "pinned": true } ``` ## Unpin a Discord message `DELETE /discord/channels/{channelId}/pins/{messageId}` Access: `write` · MCP tool: `unpin-discord-message` · Zernio: `DELETE /v1/discord/channels/{channelId}/pins/{messageId}` ### Path parameters - `channelId` (string; required; 1–512 characters) - `messageId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `reason` (string; ≤ 512 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/discord/channels/CHANNEL_ID/pins/MESSAGE_ID?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "discord_pin", "channel_id": "string", "message_id": "string", "pinned": true } ``` ## List Discord scheduled events `GET /discord/guilds/{guildId}/events` Access: `read` · MCP tool: `list-discord-events` · Zernio: `GET /v1/discord/guilds/{guildId}/events` ### Path parameters - `guildId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `with_user_count` (boolean) ```bash curl "https://api.socialit.com/v1/discord/guilds/GUILD_ID/events?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "account_id": "string", "guild_id": "string", "data": [ { "object": "discord_scheduled_event", "id": "string", "guild_id": "string", "name": "string", "description": "string", "starts_at": "2026-10-13T09:00:00.000Z", "ends_at": "2026-10-13T09:00:00.000Z", "status": "string", "entity_type": "string", "channel_id": "string", "location": "string", "user_count": 1, "image": "string", "recurrence_rule": {}, "creator_id": "string" } ], "has_more": true, "next_cursor": "string" } ``` ## Create a Discord scheduled event `POST /discord/guilds/{guildId}/events` External (location + end time), voice or stage (channel) events; always server-only privacy. Access: `write` · MCP tool: `create-discord-event` · Zernio: `POST /v1/discord/guilds/{guildId}/events` ### Path parameters - `guildId` (string; required; 1–512 characters) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `name` (string; required; 1–100 characters) - `description` (string; ≤ 1000 characters) - `starts_at` (string; required; 10–40 characters) - `ends_at` (string; 10–40 characters) - `entity` (object; required) - `entity.type` (string; required; one of external, voice, stage) - `entity.location` (string; ≤ 100 characters) - `entity.channel_id` (string; pattern ^[0-9]{5,25}$) - `entity.ends_at` (string; 10–40 characters) - `image_data_uri` (string | null; ≤ 12000000 characters): data: URI or https URL (null clears on update) - `recurrence_rule` (object) - `reason` (string; ≤ 512 characters) ```bash curl -X POST "https://api.socialit.com/v1/discord/guilds/GUILD_ID/events" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "account_id": "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "name": "string", "description": "string", "starts_at": "2026-10-13T09:00:00.000Z", "entity": { "type": "external", "location": "string" } }' ``` Response 201: ```json { "object": "discord_scheduled_event", "id": "string", "guild_id": "string", "name": "string", "description": "string", "starts_at": "2026-10-13T09:00:00.000Z", "ends_at": "2026-10-13T09:00:00.000Z", "status": "string", "entity_type": "string", "channel_id": "string", "location": "string", "user_count": 1, "image": "string", "recurrence_rule": {}, "creator_id": "string" } ``` ## Get a Discord scheduled event `GET /discord/guilds/{guildId}/events/{eventId}` Access: `read` · MCP tool: `get-discord-event` · Zernio: `GET /v1/discord/guilds/{guildId}/events/{eventId}` ### Path parameters - `guildId` (string; required; 1–512 characters) - `eventId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `with_user_count` (boolean) ```bash curl "https://api.socialit.com/v1/discord/guilds/GUILD_ID/events/EVENT_ID?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "discord_scheduled_event", "id": "string", "guild_id": "string", "name": "string", "description": "string", "starts_at": "2026-10-13T09:00:00.000Z", "ends_at": "2026-10-13T09:00:00.000Z", "status": "string", "entity_type": "string", "channel_id": "string", "location": "string", "user_count": 1, "image": "string", "recurrence_rule": {}, "creator_id": "string" } ``` ## Update a Discord scheduled event `PATCH /discord/guilds/{guildId}/events/{eventId}` Access: `write` · MCP tool: `update-discord-event` · Zernio: `PATCH /v1/discord/guilds/{guildId}/events/{eventId}` ### Path parameters - `guildId` (string; required; 1–512 characters) - `eventId` (string; required; 1–512 characters) ### Body - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `name` (string; 1–100 characters) - `description` (string | null; ≤ 1000 characters) - `starts_at` (string; 10–40 characters) - `ends_at` (string | null; ≤ 40 characters) - `location` (string; ≤ 100 characters) - `status` (string; one of scheduled, active, completed, cancelled) - `image_data_uri` (string | null; ≤ 12000000 characters): data: URI or https URL (null clears on update) - `recurrence_rule` (object | null) - `reason` (string; ≤ 512 characters) ```bash curl -X PATCH "https://api.socialit.com/v1/discord/guilds/GUILD_ID/events/EVENT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "account_id": "sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd", "name": "string", "description": "string", "starts_at": "2026-10-13T09:00:00.000Z", "ends_at": "2026-10-13T09:00:00.000Z" }' ``` Response 200: ```json { "object": "discord_scheduled_event", "id": "string", "guild_id": "string", "name": "string", "description": "string", "starts_at": "2026-10-13T09:00:00.000Z", "ends_at": "2026-10-13T09:00:00.000Z", "status": "string", "entity_type": "string", "channel_id": "string", "location": "string", "user_count": 1, "image": "string", "recurrence_rule": {}, "creator_id": "string" } ``` ## Delete a Discord scheduled event `DELETE /discord/guilds/{guildId}/events/{eventId}` Access: `write` · MCP tool: `delete-discord-event` · Zernio: `DELETE /v1/discord/guilds/{guildId}/events/{eventId}` ### Path parameters - `guildId` (string; required; 1–512 characters) - `eventId` (string; required; 1–512 characters) ### Query parameters - `account_id` (string; required; 1–80 characters): Social account id (sa_…) - `reason` (string; ≤ 512 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/discord/guilds/GUILD_ID/events/EVENT_ID?account_id=sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "discord_scheduled_event", "id": "string", "deleted": true } ``` --- Source: https://socialit.com/docs/api-reference/platform-tools/ # Focus API > Focus mode: everything a network's API allows for one connected account. The manifest lists the resources (with JSON schemas for tables and forms); the generic operations run them. Typed per-network aliases live under the "Focus · " tags. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List networks with Focus mode `GET /focus/platforms` Networks that publish a focus module, with their navigation groups, resource / action counts and MCP toolset. Access: `read` · MCP tool: `list-focus-platforms` ```bash curl "https://api.socialit.com/v1/focus/platforms" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "focus_platform", "platform": "string", "label": "string", "groups": [ { "key": "string", "label": "string", "icon": "string" } ], "resource_count": 1, "action_count": 1, "operation_count": 1, "toolset": "string" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get the Focus manifest of an account `GET /accounts/{accountId}/focus` Resources of the account's network with their JSON schemas, operations and actions. Availability is computed from the account's granted scopes; missing_scopes and reconnect_url (connect with scope_set=focus) tell how to unlock the rest. Access: `read` · MCP tool: `get-focus-manifest` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/focus" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "focus_manifest", "platform": "string", "label": "string", "account": { "object": "account", "id": "string", "platform": "string", "account_type": "string", "username": "string", "display_name": "string", "avatar_url": "https://example.com", "status": "active", "profile_id": "string", "scopes": [ "string" ] }, "groups": [ { "key": "string", "label": "string", "icon": "string" } ], "resources": [ { "key": "string", "label": "string", "description": "string", "icon": "string", "group": "string", "view": "string", "singleton": true, "id_field": "string", "title_field": "string", "columns": [ "string" ], "fields": {}, "operations": { "list": { "available": true, "query": {}, "body": {}, "summary": "string" }, "get": { "available": true, "query": {}, "body": {}, "summary": "string" }, "create": { "available": true, "query": {}, "body": {}, "summary": "string" }, "update": { "available": true, "query": {}, "body": {}, "summary": "string" }, "delete": { "available": true, "query": {}, "body": {}, "summary": "string" } }, "actions": [ { "name": "string", "label": "string", "target": "item", "destructive": true, "body": {}, "summary": "string" } ], "available": true, "missing_scopes": [ "string" ], "docs": "string", "typed_path": "string" } ], "missing_scopes": [ "string" ], "needs_reconnect": true, "reconnect_url": "https://example.com" } ``` ## List focus items (or get a singleton resource) `GET /accounts/{accountId}/focus/{resource}` Lists items of a resource with cursor pagination (cursor = previous next_cursor). Other query parameters are validated against the resource's operations.list.query schema and passed to the network. For singleton resources (singleton: true in the manifest) returns the object. Access: `read` · MCP tool: `list-focus-items` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `resource` (string; required; 1–80 characters, pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$): Focus resource key from the manifest (e.g. videos) ### Query parameters - `cursor` (string): Opaque cursor from next_cursor - `limit` (integer; 1–500): Page size (the network may cap it lower) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/focus/RESOURCE" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ {} ], "limit": 1, "total": 1, "has_more": true, "next_cursor": "string", "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Create a focus item `POST /accounts/{accountId}/focus/{resource}` Body validated against the resource's operations.create.body schema. Access: `write` · MCP tool: `create-focus-item` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `resource` (string; required; 1–80 characters, pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$): Focus resource key from the manifest (e.g. videos) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/focus/RESOURCE" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{}' ``` Response 201: ```json {} ``` ## Update a singleton focus resource `PATCH /accounts/{accountId}/focus/{resource}` For resources with singleton: true (channel settings, chat info, …). Body validated against operations.update.body. Access: `write` · MCP tool: `update-focus-singleton` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `resource` (string; required; 1–80 characters, pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$): Focus resource key from the manifest (e.g. videos) ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/focus/RESOURCE" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` Response 200: ```json {} ``` ## Delete or reset a singleton focus resource `DELETE /accounts/{accountId}/focus/{resource}` Access: `write` · MCP tool: `delete-focus-singleton` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `resource` (string; required; 1–80 characters, pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$): Focus resource key from the manifest (e.g. videos) ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/focus/RESOURCE" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "focus_item", "platform": "string", "resource": "string", "id": "string", "deleted": true, "result": null } ``` ## Get a focus item `GET /accounts/{accountId}/focus/{resource}/{itemId}` Query parameters are passed to the network (validated against operations.get.query when present). Access: `read` · MCP tool: `get-focus-item` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `resource` (string; required; 1–80 characters, pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$): Focus resource key from the manifest (e.g. videos) - `itemId` (string; required; 1–512 characters): The network's id of the item ### Query parameters - `type` (any) - `additionalProperties` (any) ```bash curl "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/focus/RESOURCE/ITEM_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json {} ``` ## Update a focus item `PATCH /accounts/{accountId}/focus/{resource}/{itemId}` Body validated against operations.update.body. Access: `write` · MCP tool: `update-focus-item` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `resource` (string; required; 1–80 characters, pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$): Focus resource key from the manifest (e.g. videos) - `itemId` (string; required; 1–512 characters): The network's id of the item ```bash curl -X PATCH "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/focus/RESOURCE/ITEM_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` Response 200: ```json {} ``` ## Delete a focus item `DELETE /accounts/{accountId}/focus/{resource}/{itemId}` Access: `write` · MCP tool: `delete-focus-item` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `resource` (string; required; 1–80 characters, pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$): Focus resource key from the manifest (e.g. videos) - `itemId` (string; required; 1–512 characters): The network's id of the item ```bash curl -X DELETE "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/focus/RESOURCE/ITEM_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "focus_item", "platform": "string", "resource": "string", "id": "string", "deleted": true, "result": null } ``` ## Run a focus action `POST /accounts/{accountId}/focus/{resource}/{itemId}/{action}` Item actions (target: "item") take the item id; collection actions (target: "collection") and actions of singleton resources use - as itemId (…/focus/{resource}/-/{action}). Body validated against the action's body schema. Access: `write` · MCP tool: `run-focus-action` ### Path parameters - `accountId` (string; required; 1–80 characters): Social account id (sa_…) - `resource` (string; required; 1–80 characters, pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$): Focus resource key from the manifest (e.g. videos) - `itemId` (string; required; 1–512 characters): The network's id of the item - `action` (string; required; 1–80 characters, pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$): Action name from the manifest (e.g. transition) ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ```bash curl -X POST "https://api.socialit.com/v1/accounts/sa_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/focus/RESOURCE/ITEM_ID/ACTION" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{}' ``` Response 200: ```json { "object": "focus_action_result", "platform": "string", "resource": "string", "action": "string", "id": "string", "result": null } ``` --- Source: https://socialit.com/docs/api-reference/focus/ # Billing API > Plans, subscriptions, payment methods, invoices, usage and prepaid credits. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## Get usage `GET /usage` Plan, limits and consumption for the current period: connected accounts against the allowance (plan included + extra accounts + lifetime + Apple seats), members, profiles, webhooks, API keys, posts, storage, API requests this hour, X API pass-through calls and spend, and prepaid credits. Also covers the deprecated usage-stats snapshot. Access: `read` · MCP tool: `get-usage` · Zernio: `GET /v1/usage`, `GET /v1/usage-stats` ```bash curl "https://api.socialit.com/v1/usage" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "usage", "plan": "free", "interval": "string", "period_start": "2026-10-13T09:00:00.000Z", "period_end": "2026-10-13T09:00:00.000Z", "accounts": { "used": 1, "included": 1, "extra_purchased": 1, "lifetime": 1, "apple": 1, "legacy_subscribed": 1, "limit": 1, "available": 1, "over_limit": 1, "paused": 1 }, "members": { "used": 1, "limit": 1 }, "profiles": { "used": 1, "limit": 1 }, "webhooks": { "used": 1, "limit": 1 }, "api_keys": { "used": 1, "limit": 1 }, "posts": { "this_month": 1, "limit_per_month": 1 }, "storage": { "used_bytes": 1, "limit_bytes": 1 }, "api": { "requests_this_hour": 1, "limit_per_hour": 1 }, "x_api": { "calls": 1, "spend_cents": 1, "calls_by_operation": { "key": 1 } }, "credits_cents": 1 } ``` ## Get X API usage `GET /usage/x-api` Metering of X API pass-through calls (debited from prepaid credits at cost) over a window: totals, per-operation breakdown and a day/month series. Pair with GET /billing/x-pricing. Profile-restricted keys only see their profiles’ accounts. Access: `read` · MCP tool: `get-x-api-usage` ### Query parameters - `range` (string; one of cycle, prev_cycle, 7d, 30d, 90d, 12mo, custom) - `from` (string (date)) - `to` (string (date)) - `granularity` (string; one of day, month, total) - `account_id` (string; pattern ^sa_[0-9A-Za-z]{27}$) ```bash curl "https://api.socialit.com/v1/usage/x-api" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "x_api_usage", "range": "string", "from": "+15551234567", "to": "+15551234567", "granularity": "string", "totals": { "calls": 1, "spend_cents": 1, "spend_micro_usd": 1 }, "by_operation": [ { "operation": "string", "calls": 1, "spend_cents": 1 } ], "days": [ { "date": "string", "calls": 1, "spend_cents": 1 } ] } ``` ## Get billing overview `GET /billing` Plan, billing interval, subscription status and period, extra accounts, recurring price, account allowance and publishing pause, payment method, invoices summary, upcoming invoice, credits and the dashboard banner. Access: `read` · MCP tool: `get-billing` · Zernio: `GET /v1/billing` ```bash curl "https://api.socialit.com/v1/billing" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "billing", "plan": "free", "plan_name": "string", "interval": "string", "status": "string", "provider": "none", "customer_id": "string", "subscription_id": "string", "current_period_start": "2026-10-13T09:00:00.000Z", "current_period_end": "2026-10-13T09:00:00.000Z", "cancel_at_period_end": true, "canceled_at": "2026-10-13T09:00:00.000Z", "extra_accounts": 1, "price": { "currency": "USD", "base_cents": 1, "extra_account_cents": 1, "extra_accounts_cents": 1, "total_cents": 1, "period": "string" }, "accounts": { "used": 1, "included": 1, "extra_purchased": 1, "lifetime": 1, "apple": 1, "legacy_subscribed": 1, "limit": 1, "available": 1, "over_limit": 1, "paused": 1 }, "publishing_paused": { "active": true, "account_ids": [ "string" ] }, "banner": { "type": "string", "severity": "string", "message": "string", "action": "string" }, "payment_method": { "object": "payment_method", "id": "string", "type": "string", "brand": "string", "last4": "string", "exp_month": 1, "exp_year": 1, "wallet": "string", "is_default": true, "created_at": "2026-10-13T09:00:00.000Z" }, "has_payment_method": true, "invoices": { "latest": { "object": "invoice", "id": "string", "number": "string", "status": "string", "currency": "USD", "amount_due_cents": 1, "amount_paid_cents": 1, "amount_remaining_cents": 1, "subtotal_cents": 1, "tax_cents": 1, "total_cents": 1, "billing_reason": "string", "description": "string", "period_start": "2026-10-13T09:00:00.000Z", "period_end": "2026-10-13T09:00:00.000Z", "hosted_invoice_url": "https://example.com", "invoice_pdf": "string", "due_date": "2026-10-13T09:00:00.000Z", "paid_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "lines": [ { "description": "string", "amount_cents": 1, "quantity": 1, "period_start": "2026-10-13T09:00:00.000Z", "period_end": "2026-10-13T09:00:00.000Z" } ] }, "open_count": 1, "open_amount_cents": 1 }, "upcoming_invoice": { "amount_due_cents": 1, "currency": "USD", "next_payment_attempt": "2026-10-13T09:00:00.000Z" }, "credits_cents": 1, "x_usage_blocked": true, "legacy": { "billing_mode": "string", "lifetime_seats": 1, "subscribed_seats": 1, "apple_seats": 1, "source": "string", "metered": true } } ``` ## List plans `GET /billing/plans` Prices (price_cents per month, year = per month billed yearly; billed_cents per billing period), extra account prices, limits and features of every plan. Access: `read` · MCP tool: `list-plans` ```bash curl "https://api.socialit.com/v1/billing/plans" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "plan", "id": "free", "name": "string", "rank": 1, "self_serve": true, "current": true, "price_cents": { "month": 1, "year": 1 }, "billed_cents": { "month": 1, "year": 1 }, "extra_account_cents": { "month": 1, "year": 1 }, "extra_account_billed_cents": { "month": 1, "year": 1 }, "limits": {}, "features": {} } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get X API pricing `GET /billing/x-pricing` The X API pass-through price table (zero markup) by operation and tier. Safe to cache for a billing period. Access: `read` · MCP tool: `get-x-pricing` · Zernio: `GET /v1/billing/x-pricing` ```bash curl "https://api.socialit.com/v1/billing/x-pricing" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "x_pricing", "currency": "USD", "markup": "string", "source": "string", "last_verified": "string", "tiers": [ { "tier": "string", "price_per_call_usd": 1.5, "operation_count": 1 } ], "operations": [ { "operation": "string", "display_name": "string", "price_per_call_usd": 1.5, "price_per_call_cents": 1.5, "price_micro_usd": 1, "tier": "string", "triggered_by": [ "string" ] } ] } ``` ## Get prepaid credits `GET /billing/credits` Credit balance (USD cents) used for X API pass-through calls, whether X actions are blocked, and the credit packs for sale. Access: `read` · MCP tool: `get-billing-credits` ```bash curl "https://api.socialit.com/v1/billing/credits" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "credits", "balance_cents": 1, "x_usage_blocked": true, "packs": [ { "id": "string", "price_cents": 1, "credits_cents": 1, "ios_product_id": "string" } ] } ``` ## Preview a plan change `GET /billing/preview` Recurring price and the proration due now for switching plan, interval or extra accounts. Without a subscription the preview is the first period (requires_checkout: true). Upgrades are invoiced immediately; downgrades credit the next invoice. Access: `read` · MCP tool: `preview-billing-change` ### Query parameters - `plan` (string; required; one of free, pro, business, enterprise) - `interval` (string; one of month, year) - `extra_accounts` (integer; 0–100000) ```bash curl "https://api.socialit.com/v1/billing/preview?plan=value" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "billing_preview", "plan": "string", "interval": "string", "extra_accounts": 1, "change_type": "new", "requires_checkout": true, "currency": "USD", "recurring": { "base_cents": 1, "extra_accounts_cents": 1, "total_cents": 1, "period": "string" }, "amount_due_now_cents": 1, "proration_date": 1, "lines": [ { "description": "string", "amount_cents": 1, "proration": true, "period_start": "2026-10-13T09:00:00.000Z", "period_end": "2026-10-13T09:00:00.000Z" } ], "next_invoice_at": "2026-10-13T09:00:00.000Z", "accounts": { "used": 1, "limit_after": 1, "over_limit_after": 1 } } ``` ## List invoices `GET /billing/invoices` Stripe invoices of the workspace, newest first, with hosted page and PDF links. Access: `read` · MCP tool: `list-billing-invoices` ### Query parameters - `page` (integer; 1–50) - `limit` (integer; 1–100) - `status` (string; one of draft, open, paid, uncollectible, void) ```bash curl "https://api.socialit.com/v1/billing/invoices" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "invoice", "id": "string", "number": "string", "status": "string", "currency": "USD", "amount_due_cents": 1, "amount_paid_cents": 1, "amount_remaining_cents": 1, "subtotal_cents": 1, "tax_cents": 1, "total_cents": 1, "billing_reason": "string", "description": "string", "period_start": "2026-10-13T09:00:00.000Z", "period_end": "2026-10-13T09:00:00.000Z", "hosted_invoice_url": "https://example.com", "invoice_pdf": "string", "due_date": "2026-10-13T09:00:00.000Z", "paid_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "lines": [ { "description": "string", "amount_cents": 1, "quantity": 1, "period_start": "2026-10-13T09:00:00.000Z", "period_end": "2026-10-13T09:00:00.000Z" } ] } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Get an invoice `GET /billing/invoices/{id}` Access: `read` · MCP tool: `get-billing-invoice` ### Path parameters - `id` (string; required; pattern ^in_[A-Za-z0-9_]+$) ```bash curl "https://api.socialit.com/v1/billing/invoices/ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "invoice", "id": "string", "number": "string", "status": "string", "currency": "USD", "amount_due_cents": 1, "amount_paid_cents": 1, "amount_remaining_cents": 1, "subtotal_cents": 1, "tax_cents": 1, "total_cents": 1, "billing_reason": "string", "description": "string", "period_start": "2026-10-13T09:00:00.000Z", "period_end": "2026-10-13T09:00:00.000Z", "hosted_invoice_url": "https://example.com", "invoice_pdf": "string", "due_date": "2026-10-13T09:00:00.000Z", "paid_at": "2026-10-13T09:00:00.000Z", "created_at": "2026-10-13T09:00:00.000Z", "lines": [ { "description": "string", "amount_cents": 1, "quantity": 1, "period_start": "2026-10-13T09:00:00.000Z", "period_end": "2026-10-13T09:00:00.000Z" } ] } ``` --- Source: https://socialit.com/docs/api-reference/billing/ # Connected Apps API > Third-party apps and AI agents connected with OAuth. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List connected apps `GET /me/connected-apps` With an API key: apps that can reach this workspace (admin keys). In the dashboard: apps you approved. Access: `read` · Zernio: `GET /v1/me/connected-apps` ```bash curl "https://api.socialit.com/v1/me/connected-apps" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "connected_app", "client_id": "string", "client_name": "string", "client_uri": "string", "logo_uri": "string", "scopes": [ "string" ], "workspaces": [ { "id": "string", "name": "string", "role": "string" } ], "created_at": "2026-10-13T09:00:00.000Z", "last_used_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Revoke a connected app `DELETE /me/connected-apps/{clientId}` With an API key the app loses access to this workspace only; in the dashboard every grant you gave the app is revoked. Access: `read` · Zernio: `DELETE /v1/me/connected-apps/{clientId}` ### Path parameters - `clientId` (string; required; 1–2048 characters) ```bash curl -X DELETE "https://api.socialit.com/v1/me/connected-apps/CLIENT_ID" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "connected_app", "id": "string", "deleted": true } ``` --- Source: https://socialit.com/docs/api-reference/connected-apps/ # Support Assistant API > Ask Socialit support questions (failed posts, account connection, API usage). Answers are generated with Claude, grounded on the Socialit documentation and on the context you pass (post, account, failed request). Runs are asynchronous: poll the run or listen to support_run.completed. Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer `. ## List a thread's support answers `GET /support/runs` With thread_id: the whole thread, oldest first. Without: every run of the workspace, newest first. Access: `read` · MCP tool: `list-support-runs` · Zernio: `GET /v1/support/runs` ### Query parameters - `page` (integer; ≥ 1): Page number - `limit` (integer; 1–100): Items per page (max 100) - `sort` (string; one of created_at) - `order` (string; one of asc, desc) - `match` (string; one of all, or): Combine filters with AND (default) or OR - `thread_id` (string; ≤ 80 characters) - `status` (string) ```bash curl "https://api.socialit.com/v1/support/runs" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "list", "data": [ { "object": "support_run", "id": "string", "thread_id": "string", "status": "queued", "stop_reason": "string", "question": "string", "answer": "string", "diagnosis": { "category": "account_connection", "cause": "string", "fix_steps": [ "string" ], "docs_links": [ "string" ], "who_must_act": "integrator" }, "sources": [ { "title": "string", "path": "string", "url": "https://example.com" } ], "context": { "post_id": "string", "account_id": "string", "profile_id": "string", "request_id": "string" }, "model": "string", "usage": { "input_tokens": 1, "output_tokens": 1, "cache_read_tokens": 1, "cache_write_tokens": 1 }, "cost_usd": 1.5, "max_cost_usd": 1.5, "support_ticket": { "opened_at": "2026-10-13T09:00:00.000Z" }, "poll_after_seconds": 1, "created_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "finished_at": "2026-10-13T09:00:00.000Z" } ], "page": 1, "limit": 1, "total": 1, "has_more": true, "next_page_url": "https://example.com", "previous_page_url": "https://example.com" } ``` ## Ask a support question `POST /support/runs` Returns 202 with a queued run. 503 support_unavailable when the server has no Anthropic API key; 409 support_run_in_progress (one active run per thread); 429 support_active_runs_limit (3 at once). Access: `write` · MCP tool: `ask-support-question` · Zernio: `POST /v1/support/runs` ### Headers - `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours. ### Body - `message` (string; required; 1–10000 characters) - `thread_id` (string; ≤ 80 characters) - `context` (object) - `context.post_id` (string) - `context.account_id` (string) - `context.profile_id` (string) - `context.request_id` (string; ≤ 128 characters) - `max_cost_usd` (number; 0.05–3) ```bash curl -X POST "https://api.socialit.com/v1/support/runs" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "message": "string", "thread_id": "string", "context": { "post_id": "string", "account_id": "string" }, "max_cost_usd": 0.05 }' ``` Response 202: ```json { "object": "support_run", "id": "string", "thread_id": "string", "status": "queued", "stop_reason": "string", "question": "string", "answer": "string", "diagnosis": { "category": "account_connection", "cause": "string", "fix_steps": [ "string" ], "docs_links": [ "string" ], "who_must_act": "integrator" }, "sources": [ { "title": "string", "path": "string", "url": "https://example.com" } ], "context": { "post_id": "string", "account_id": "string", "profile_id": "string", "request_id": "string" }, "model": "string", "usage": { "input_tokens": 1, "output_tokens": 1, "cache_read_tokens": 1, "cache_write_tokens": 1 }, "cost_usd": 1.5, "max_cost_usd": 1.5, "support_ticket": { "opened_at": "2026-10-13T09:00:00.000Z" }, "poll_after_seconds": 1, "created_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "finished_at": "2026-10-13T09:00:00.000Z" } ``` ## Get a support answer `GET /support/runs/{id}` Access: `read` · MCP tool: `get-support-run` · Zernio: `GET /v1/support/runs/{runId}` ### Path parameters - `id` (string; required; 1–80 characters): supportRun id (srun_…) ```bash curl "https://api.socialit.com/v1/support/runs/srun_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \ -H "Authorization: Bearer $SOCIALIT_API_KEY" ``` Response 200: ```json { "object": "support_run", "id": "string", "thread_id": "string", "status": "queued", "stop_reason": "string", "question": "string", "answer": "string", "diagnosis": { "category": "account_connection", "cause": "string", "fix_steps": [ "string" ], "docs_links": [ "string" ], "who_must_act": "integrator" }, "sources": [ { "title": "string", "path": "string", "url": "https://example.com" } ], "context": { "post_id": "string", "account_id": "string", "profile_id": "string", "request_id": "string" }, "model": "string", "usage": { "input_tokens": 1, "output_tokens": 1, "cache_read_tokens": 1, "cache_write_tokens": 1 }, "cost_usd": 1.5, "max_cost_usd": 1.5, "support_ticket": { "opened_at": "2026-10-13T09:00:00.000Z" }, "poll_after_seconds": 1, "created_at": "2026-10-13T09:00:00.000Z", "started_at": "2026-10-13T09:00:00.000Z", "finished_at": "2026-10-13T09:00:00.000Z" } ``` --- Source: https://socialit.com/docs/api-reference/support-assistant/