# 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 <API key or OAuth token>`. 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/
