# OmniSocials developer docs

> OmniSocials schedules, publishes and answers social media posts on 12 platforms (Instagram, Facebook, LinkedIn, YouTube, TikTok, X, Pinterest, Threads, Bluesky, Mastodon, Google Business, Telegram) through one REST API, 8 SDKs, a hosted MCP server and a CLI.

Guidance for agents:

- Every page link below is markdown. Any docs page is also available by adding .md to its URL, or by sending `Accept: text/markdown` to the page URL.
- Search and read these docs from an MCP client at https://docs.omnisocials.com/mcp (tools: search_docs, get_page, get_endpoint, list_pages). Setup: https://docs.omnisocials.com/ai-agents.md
- To act on a workspace from an AI assistant (post, schedule, read the inbox), use the OmniSocials MCP server at https://mcp.omnisocials.com. See https://docs.omnisocials.com/mcp-server.md
- REST base URL: https://api.omnisocials.com/v1. Auth: `Authorization: Bearer omsk_live_...`. There is no test mode. Social accounts are connected in the dashboard only, never through the API.
- 12 platforms, 13 channels: LinkedIn has a personal profile channel and a company page channel.

## Start here

- [Quickstart: publish your first post](https://docs.omnisocials.com/introduction.md): Get an OmniSocials API key and publish your first post in five steps, to 13 channels on 12 platforms. Examples in curl, Node.js and Python.
- [API authentication and API keys](https://docs.omnisocials.com/authentication.md): Create OmniSocials API keys, pick scopes, and authenticate with Bearer tokens. Covers the scope reference, opt-in inbox and automation scopes, and key rotation.
- [Test your OmniSocials API integration safely](https://docs.omnisocials.com/testing.md): OmniSocials has no sandbox: every key is live. How to test with drafts, a test workspace, private posts, webhook request bins, and the Postman collection.
- [API rate limits and error codes](https://docs.omnisocials.com/rate-limits-and-errors.md): The OmniSocials API allows 100 requests per minute per key. Full HTTP status table, the shared error body shape, stable error codes, and a retry strategy.
- [Retries and duplicate posts: retry safely](https://docs.omnisocials.com/retries.md): How the OmniSocials API handles timeouts, 5xx errors and failed posts: no idempotency keys, the retry endpoint, automatic retries, and avoiding double posts.
- [Use the OmniSocials docs from an AI agent](https://docs.omnisocials.com/ai-agents.md): Read the OmniSocials docs from an AI agent or coding tool: llms.txt, markdown pages, the docs MCP server, the OpenAPI spec and a Postman collection.

## Guides

- [Create and schedule posts via API](https://docs.omnisocials.com/creating-posts.md): Create, schedule, and publish social posts via the OmniSocials API: per-platform content, media, alt text, first comments, hashtag sets, post statuses, and retries.
- [Post Stories via API to Instagram and Facebook](https://docs.omnisocials.com/creating-stories.md): Publish 24-hour stories to Instagram and Facebook via API: media requirements, scheduling, and what happens after a story expires.
- [Post Reels via API to Instagram and TikTok](https://docs.omnisocials.com/creating-reels.md): Publish short-form vertical video to Instagram Reels, Facebook Reels, YouTube Shorts, and TikTok in one API call. Per-platform options and media specs.
- [Cross-post to 12 channels in one API call](https://docs.omnisocials.com/cross-posting.md): Publish one post to 12 social channels in a single API call: per-platform content overrides, media targeting, character limits, and partial-failure handling.
- [Upload images, video and PDFs via API](https://docs.omnisocials.com/media.md): Upload images, video, and PDFs to the OmniSocials media library: direct upload to 100 MB, URL ingest to 1 GB, PDF-to-carousel, alt text, and supported formats.
- [Social media analytics API: post and account metrics](https://docs.omnisocials.com/analytics.md): Pull post-level metrics, workspace overviews, follower counts, and data-driven best posting times for 12 social channels through one API. Includes bulk retrieval for up to 100 posts per call.
- [Social inbox API: DMs, comments and mentions](https://docs.omnisocials.com/inbox.md): Read and reply to DMs, comments, and mentions across platforms with the OmniSocials Social Inbox API: conversations, pagination, the next-unanswered work queue, hiding and deleting comments, reply limits, and errors.
- [Comment-to-DM Automations API: Instagram keyword DMs](https://docs.omnisocials.com/automations.md): Send a DM to everyone who comments a keyword on an Instagram post with the OmniSocials Automations API: triggers, scopes, public replies, limits, the activity log, and the comment_dm_automation field on posts.
- [Webhooks for post events](https://docs.omnisocials.com/webhooks.md): Subscribe to post.published, post.failed, post.approved, post.rejected and other OmniSocials webhook events. Payload schemas, HMAC signature verification, and secret rotation.

## Platforms

- [13 supported social channels](https://docs.omnisocials.com/platforms.md): Channel identifiers, content-type support, and media specs for all 13 OmniSocials channels, plus the platforms coming next.
- [Known issues and platform limits](https://docs.omnisocials.com/known-issues.md): Platform quirks that make OmniSocials posts fail or behave unexpectedly, per channel: the error you see, why it happens, and what to do about it.
- [Bluesky API: posting reference](https://docs.omnisocials.com/platforms/bluesky.md): Post to Bluesky via API: threads, images with alt text, automatic link cards, automatic image compression to the 2 MB cap, and the 300-grapheme limit.
- [Facebook API: posting reference](https://docs.omnisocials.com/platforms/facebook.md): Post to Facebook Pages via the OmniSocials API: feed posts, multi-photo and link posts, Reels, stories, first comments, media specs, and character limits.
- [Google Business Profile API: posting reference](https://docs.omnisocials.com/platforms/google-business.md): Publish Google Business Profile posts via the OmniSocials API: CTA buttons, image rules, and what its analytics do and do not report.
- [Instagram API: posting reference](https://docs.omnisocials.com/platforms/instagram.md): Publish posts, carousels, Reels, and stories to Instagram via API: media specs, collaborators, location tags, user tags, alt text, comment-to-DM automations, and the 5-hashtag cap.
- [LinkedIn API: posting reference](https://docs.omnisocials.com/platforms/linkedin.md): Post to LinkedIn profiles and company pages via API: native document carousels, the original PDF, polls, first comments, and media specs.
- [Mastodon API: posting reference](https://docs.omnisocials.com/platforms/mastodon.md): Post to any Mastodon instance via the OmniSocials API: threads, polls, media, and per-instance character limits read at connect time.
- [Pinterest API: posting reference](https://docs.omnisocials.com/platforms/pinterest.md): Create image, video, and carousel pins via the OmniSocials API: boards, destination links, alt text, product tags, and aspect-ratio rules.
- [Telegram API: posting reference](https://docs.omnisocials.com/platforms/telegram.md): Post to a Telegram channel or group via the OmniSocials API: photos, videos, albums, native polls, link buttons, pins and silent posts.
- [Threads API: posting reference](https://docs.omnisocials.com/platforms/threads.md): Post to Threads via the OmniSocials API: text, images, video, mixed carousels, multi-post threads, polls, the Social Inbox, alt text, and the 500-character limit.
- [TikTok API: posting reference](https://docs.omnisocials.com/platforms/tiktok.md): Post videos and image carousels to TikTok via API: privacy levels, media specs up to 1 GB, and the caption caps (2,200 for videos, 4,000 for photo posts).
- [X (Twitter) API: posting reference](https://docs.omnisocials.com/platforms/x.md): Post to X (Twitter) via API: threads, polls, media, weighted character counting (links count as 23), Premium limits, link-post credits, and the DM inbox.
- [YouTube API: posting reference](https://docs.omnisocials.com/platforms/youtube.md): Publish YouTube Shorts via the OmniSocials API: titles, descriptions, privacy status, first comments, comments in the Social Inbox, analytics, and media requirements.

## SDKs

- [SDKs: install and use the OmniSocials API in 8 languages](https://docs.omnisocials.com/sdks.md): Official OmniSocials SDKs for Node.js, Python, Go, Ruby, PHP, Java, .NET, and Rust. Install, authenticate, and publish your first post in a few lines.
- [Node.js SDK reference: install, auth and methods](https://docs.omnisocials.com/sdks/node.md): The official Node.js SDK for the OmniSocials API: npm install, authenticate, publish, schedule, upload media, and read analytics with TypeScript types.
- [Python SDK reference: install, auth and methods](https://docs.omnisocials.com/sdks/python.md): The official Python SDK for the OmniSocials API: pip install, authenticate, publish, schedule, upload media, and read analytics.
- [.NET SDK reference: install, auth and methods](https://docs.omnisocials.com/sdks/dotnet.md): The official .NET SDK for the OmniSocials API: NuGet install, authenticate, publish, schedule, upload media, and read analytics.
- [Go SDK reference: install, auth and methods](https://docs.omnisocials.com/sdks/go.md): The official Go SDK for the OmniSocials API: go get, authenticate, publish, schedule, upload media, and read analytics.
- [Java SDK reference: install, auth and methods](https://docs.omnisocials.com/sdks/java.md): The official Java SDK for the OmniSocials API: Maven or Gradle install, authenticate, publish, schedule, and read analytics.
- [PHP SDK reference: install, auth and methods](https://docs.omnisocials.com/sdks/php.md): The official PHP SDK for the OmniSocials API: Composer install, authenticate, publish, schedule, upload media, and read analytics.
- [Ruby SDK reference: install, auth and methods](https://docs.omnisocials.com/sdks/ruby.md): The official Ruby SDK for the OmniSocials API: gem install, authenticate, publish, schedule, upload media, and read analytics.
- [Rust SDK reference: install, auth and methods](https://docs.omnisocials.com/sdks/rust.md): The official Rust SDK for the OmniSocials API: cargo add, authenticate, publish, schedule, upload media, and read analytics.

## CLI

- [CLI: post to social media from your terminal](https://docs.omnisocials.com/cli.md): Post to 12 social channels from your terminal with the OmniSocials CLI: publish, schedule, upload media, read analytics, and manage your inbox.
- [CLI analytics commands](https://docs.omnisocials.com/cli/analytics.md): OmniSocials CLI analytics commands: post metrics, bulk stats, workspace overviews, account snapshots, and best posting times.
- [CLI inbox commands](https://docs.omnisocials.com/cli/inbox.md): OmniSocials CLI inbox commands: list conversations, work through what needs an answer, read message history, reply, and hide or delete comments.
- [CLI account management commands](https://docs.omnisocials.com/cli/management.md): OmniSocials CLI management commands: workspaces, media library, folders, hashtag sets, and webhooks.
- [CLI platform commands](https://docs.omnisocials.com/cli/platforms.md): OmniSocials CLI platform commands: list connected accounts and inspect per-platform capabilities.
- [CLI posting commands](https://docs.omnisocials.com/cli/posting.md): OmniSocials CLI posting commands: create, schedule, publish, retry, and delete posts from the terminal.

## MCP and integrations

- [MCP server for social media posting](https://docs.omnisocials.com/mcp-server.md): Connect AI assistants to OmniSocials over MCP: a hosted remote endpoint (OAuth or API key) plus an npm package for stdio clients like Claude Desktop and Cursor.
- [AI and automation integrations](https://docs.omnisocials.com/integrations.md): Connect OmniSocials to Claude, ChatGPT, Grok, n8n, Make, Zapier, and agent frameworks like LangChain and CrewAI via MCP, agent skills, or the REST API.
- [Connect AI agent frameworks to the OmniSocials MCP server](https://docs.omnisocials.com/integrations/agent-frameworks.md): Give agents built with the OpenAI Agents SDK, Vercel AI SDK, LangChain, Mastra, or CrewAI the hosted OmniSocials MCP server. Code samples and API key auth.
- [Post to social media with Agent Skills](https://docs.omnisocials.com/integrations/agent-skills.md): Install the OmniSocials agent skill and CLI for Claude Code, Codex, and other coding agents.
- [Post to social media from ChatGPT](https://docs.omnisocials.com/integrations/chatgpt.md): Connect ChatGPT to OmniSocials as a custom MCP plugin with OAuth and manage your social media from a chat. No Developer mode needed.
- [Post to social media from Claude](https://docs.omnisocials.com/integrations/claude.md): Connect Claude to OmniSocials: the claude.ai connector, Claude Desktop, and Claude Code via MCP. Post, schedule, and read analytics from a chat.
- [Post to social media from Grok](https://docs.omnisocials.com/integrations/grok.md): Connect Grok to OmniSocials via the remote MCP connector. Post, schedule, and read analytics from a chat on grok.com.
- [Post to social media from Make](https://docs.omnisocials.com/integrations/make.md): Schedule and publish social media posts from a Make scenario with the HTTP app's Make a request module and the OmniSocials REST API.
- [Post to social media from Muse](https://docs.omnisocials.com/integrations/muse.md): Connect Muse, Meta's personal AI agent, to OmniSocials with a custom connector and your API key. Post, schedule, and read analytics from a Muse chat.
- [Post to social media from n8n](https://docs.omnisocials.com/integrations/n8n.md): Schedule and publish social posts from n8n with the HTTP Request node, or give an n8n AI Agent the OmniSocials MCP server as a tool.
- [Post to social media from Notion](https://docs.omnisocials.com/integrations/notion.md): Connect a Notion Custom Agent to OmniSocials via MCP and publish social posts straight from your Notion workspace.
- [Post to social media from OpenClaw](https://docs.omnisocials.com/integrations/openclaw.md): Connect OpenClaw to OmniSocials: the remote MCP server (Streamable HTTP) with an API key or OAuth, or the npm MCP package.
- [OmniSocials on Smithery](https://docs.omnisocials.com/integrations/smithery.md): OmniSocials is listed on Smithery, an MCP server registry and gateway. Connect through Smithery or directly via our own remote MCP endpoint.
- [Post to social media from Zapier](https://docs.omnisocials.com/integrations/zapier.md): Schedule and publish social posts from a Zap with Webhooks by Zapier and the OmniSocials REST API. Covers JSON escaping and the steps that need a paid plan.

## Migrate from another API

- [Migrate to the OmniSocials API](https://docs.omnisocials.com/migrate.md): Guides for moving a social posting integration from Ayrshare, Zernio (Late), Upload-Post, or the Postiz public API to the OmniSocials API.
- [Migrate from Ayrshare to the OmniSocials API](https://docs.omnisocials.com/migrate/ayrshare.md): Move an Ayrshare integration to the OmniSocials API: profile keys to workspaces, endpoint and field mapping, media, scheduling, webhooks, and platforms.
- [Migrate from the Postiz public API to the OmniSocials API](https://docs.omnisocials.com/migrate/postiz.md): Move a Postiz public API integration to the OmniSocials API: auth, endpoint and field mapping, media, threads, scheduling, webhooks, and platform coverage.
- [Migrate from Upload-Post to the OmniSocials API](https://docs.omnisocials.com/migrate/upload-post.md): Move an Upload-Post integration to the OmniSocials API: auth, endpoint and field mapping, media uploads, scheduling, webhooks, and platform coverage.
- [Migrate from Zernio (Late) to the OmniSocials API](https://docs.omnisocials.com/migrate/zernio.md): Move a Zernio (formerly Late) integration to the OmniSocials API: auth, endpoint and field mapping, media, scheduling, webhooks, and platform coverage.

## Reference

- [Glossary of OmniSocials API terms](https://docs.omnisocials.com/glossary.md): Short definitions of OmniSocials API terms: workspaces, channels, accounts, posts, media, the inbox, webhooks, MCP and the CLI, with the field each maps to.
- [Changelog](https://docs.omnisocials.com/changelog.md)

## Plans and billing

- [Social media API pricing: $10 per seat](https://docs.omnisocials.com/pricing.md): OmniSocials costs $10 per seat a month billed yearly, or $12 monthly. Every plan includes the full REST API, 8 SDKs, the CLI, the MCP server and webhooks.
- [Billing and subscription management](https://docs.omnisocials.com/billing.md): Manage your OmniSocials subscription: plans, seats, invoices, credits for X link posts, and how to change or cancel billing.
- [Affiliate program: 25% for a year](https://docs.omnisocials.com/affiliate.md): Earn 25% of every payment from each customer you refer to OmniSocials, for 12 months. 90-day cookie, free to join.

## API reference

The reference pages are HTML; for one endpoint as JSON, use the docs MCP tool get_endpoint or the OpenAPI file.

- [API overview](https://docs.omnisocials.com/api): base URL, authentication and rate limits
- [Posts](https://docs.omnisocials.com/api/posts): Create, schedule, update, publish, and delete social media posts across every connected channel.
- [Media](https://docs.omnisocials.com/api/media): Upload and manage images, video, and PDFs (up to 100 MB per upload, 1 GB from a URL) for use in posts, reels, stories, and PDF carousels.
- [Folders](https://docs.omnisocials.com/api/folders): Organize uploaded media into folders: list, create, and delete them to keep large asset libraries manageable.
- [Hashtag Sets](https://docs.omnisocials.com/api/hashtag-sets): Save reusable, named groups of hashtags per workspace and apply one to a new post in a single call, appended to captions or dropped into the auto first comment.
- [Accounts](https://docs.omnisocials.com/api/accounts): List and inspect the social accounts connected to a workspace across all 12 supported platforms.
- [Analytics](https://docs.omnisocials.com/api/analytics): Fetch post-level and account-level metrics (impressions, engagement, reach, and follower stats) in single or bulk requests.
- [Approvals](https://docs.omnisocials.com/api/approvals): Approval workflows (configured in the dashboard).
- [Webhooks](https://docs.omnisocials.com/api/webhooks): Manage webhook subscriptions for real-time events (post.scheduled, post.published, post.failed, post.approved, post.rejected).
- [Locations](https://docs.omnisocials.com/api/locations): Search and attach location tags (such as Instagram place tags) to posts.
- [Audio](https://docs.omnisocials.com/api/audio): Search and attach Instagram audio tracks, including trending music, to reels.
- [Pinterest](https://docs.omnisocials.com/api/pinterest): List and check the product Pins of the connected Pinterest account, to tag products on a Pin with `pinterest.product_tags`.
- [Inbox](https://docs.omnisocials.com/api/inbox): Read and reply to Instagram and Facebook DMs, comments, and mentions, LinkedIn company-page comments and mentions (LinkedIn has no API DMs), TikTok video comments (comments only; replies capped at 150 characters), YouTube video comments, X DMs for opted-in workspaces, and Threads replies and mentions.
- [Automations](https://docs.omnisocials.com/api/automations): Comment-to-DM automations on the connected Instagram account: a keyword in a comment on a post (or in a DM, or in a story reply) gets a DM back, once per person, with an optional public reply under the comment.

## Machine-readable files

- [OpenAPI spec](https://docs.omnisocials.com/openapi.json): every REST endpoint
- [Postman collection](https://docs.omnisocials.com/omnisocials.postman_collection.json): import into Postman, Insomnia or Bruno
- [llms-full.txt](https://docs.omnisocials.com/llms-full.txt): all guide pages in one file
- [skill.md](https://docs.omnisocials.com/skill.md): short working instructions for a coding agent
- Docs MCP server: https://docs.omnisocials.com/mcp