OmniSocials

OmniSocials API

The OmniSocials REST API schedules, publishes and analyzes posts on 13 social platforms. Upload media, receive webhooks and answer your social inbox. It…

Social#social

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The OmniSocials REST API schedules, publishes and analyzes posts on 13 social platforms. Upload media, receive webhooks and answer your social inbox.

It covers 13 platforms and 14 channels, because LinkedIn has a personal profile and a company page: Instagram, Facebook, LinkedIn (profile and page), YouTube, TikTok, X, Pinterest, Threads, Bluesky, Mastodon, Google Business, Telegram and Discord.

Base URL

https://api.omnisocials.com/v1

Authentication

Send an API key as a Bearer token in the Authorization header:

Authorization: Bearer omsk_live_your_api_key_here

Create keys in the OmniSocials dashboard under Settings > API, and give each key only the scopes it needs. The Authentication guide lists every scope.

Rate limits

Each API key can make 100 requests per minute. Responses carry these headers:

  • X-RateLimit-Limit: requests allowed per minute
  • X-RateLimit-Remaining: requests left in the current window
  • X-RateLimit-Reset: Unix time, in seconds, when the window resets

Over the limit, the API returns 429 with the code rate_limit_exceeded and a Retry-After header in seconds. See Rate limits and errors.

Endpoints 78

Posts

  • GETList posts/posts
  • GETList live platform posts/posts/recent-platformReturns the most recent posts pulled directly from each connected platform's API (Instagram, TikTok, X, YouTube, Facebook, LinkedIn, and more), including…
  • GETGet a post/posts/:id
  • DELETEDelete a post/posts/:idRemoves the post from OmniSocials only: it leaves the calendar, the posts list and the analytics. It never deletes the live post on a platform, so a published…
  • PATCHUpdate a post/posts/:id
  • POSTCreate a post/posts/createCreate a new post. You can attach media by uploading first (media/media_ids) or by passing external URLs (media_urls) which will be downloaded and processed…
  • POSTCreate and publish post/posts/create-and-publishCreates a new post and publishes it right away, with no scheduling needed. Equivalent to calling POST /posts/create with publish_now: true. The post will be…
  • POSTPublish a post now/posts/:id/publish
  • POSTRetry failed post/posts/:id/retryRe-publishes ONLY the platforms that failed, on the same post. Platforms that already succeeded are never re-published. A platform whose error says publishing…
  • POSTApprove a post/posts/:id/approveApproves the current step of the post's approval workflow, on behalf of the user who owns this API key. That user must be a listed approver for the workflow's…
  • POSTReject a post/posts/:id/rejectRejects the post's approval workflow on behalf of the user who owns this API key. That user must be a listed approver for the workflow's CURRENT step. Unlike…
  • GETGet approval review/posts/:id/approvalReturns the review of a post that went through an approval workflow: every step with its approvers and their decisions, the rejection with its reason, and the…

Media

  • GETList media/media
  • GETGet a media item/media/:idFetch one media item by id. Use this to poll a large URL upload until its status becomes ready (or failed).
  • DELETEDelete a media item/media/:id
  • PATCHRename or move media/media/:idUpdate the human-readable name and/or move a media file into a folder. Lets you label assets so they can be found later by name instead of re-uploading. Only…
  • POSTUpload a file/media/uploadUpload an image or video, or a PDF. A PDF is rasterized into one image slide per page and returned as a carousel (see PdfUploadResult): pass all of media_ids…
  • POSTUpload from base64/media/upload-from-base64Upload a file from base64-encoded data. Useful for MCP integrations where the AI has image data but no URL. Accepts images, video, and PDF (a PDF is split…
  • POSTUpload from a URL/media/upload-from-urlDownload a file from a URL and upload it to your media library. It is the recommended path for MCP/programmatic uploads. Supports videos up to 1 GB: files…
  • POSTCreate an upload URL/media/create-upload-urlCreate a one-time upload URL, for code that cannot send the API key with the upload, such as an AI assistant's code sandbox. POST the file as multipart file…
  • POSTSplit a PDF into pages/media/:id/splitFor a media item of type document (a PDF kept as one item): creates one image media item per rendered page, in page order, each a copy of the page image and…
  • POSTCheck media limits/media/checkPreflight a file against the platforms connected to your workspace and find out which (if any) would reject it by size or format, before you upload or post.…
  • POSTUpload with a token/media/upload-by-token?upload_token=9f2c4e1ab07dUpload a file to a one-time URL from POST /media/create-upload-url. No API key: the upload_token query parameter is the auth, valid once for 10 minutes. Takes…

Folders

  • GETList folders/foldersReturns all folders in the workspace as a flat list (build the tree client-side via parent_id). Use folder ids with the media endpoints to organize and find…
  • POSTCreate a folder/folders
  • DELETEDelete a folder/folders/:idDeletes the folder. Its media is NOT deleted - files move to the root ("All media"), and any subfolders move up to this folder's parent.
  • PATCHRename or move a folder/folders/:id

Hashtag Sets

  • GETList hashtag sets/hashtag-setsReturns all saved hashtag sets in the workspace. Apply one to a new post by passing its name (hashtag_set) or id (hashtag_set_id) to POST /posts/create.
  • POSTCreate a hashtag set/hashtag-setsSaves a reusable, named group of hashtags. Tags may be passed with or without the leading '#'; they are deduped case-insensitively and stored in order. Max…
  • GETGet a hashtag set/hashtag-sets/:id
  • DELETEDelete a hashtag set/hashtag-sets/:idDeletes the set. Posts that already used it are unaffected. The tags were merged into their captions at create time.
  • PATCHUpdate a hashtag set/hashtag-sets/:idRename the set and/or replace its hashtags. hashtags replaces the full list (fetch, modify, resend to add/remove tags).

Tags

  • GETList tags/tagsEvery tag of the workspace, by name. Tags label posts to filter and compare them: tag on GET /posts and GET /analytics/overview, and GET /analytics/tags.
  • POSTCreate a tag/tagsAt most 200 tags per workspace. A name is unique in the workspace (case-insensitive).
  • DELETEDelete a tag/tags/:idDeletes the tag and takes it off every post of the workspace. The posts themselves stay.
  • PATCHUpdate a tag/tags/:idRename or recolour. A key you leave out keeps its value. Posts keep the tag.
  • POSTTag posts in bulk/tags/applyAdd, remove or replace the tags of up to 500 posts at once, published ones included (tags never go to a platform). add, remove and set take tag ids or names;…

Accounts

  • GETList accounts/accountsLists the social accounts connected to the workspace of this API key, one entry per channel. Requires the accounts:read scope.
  • GETGet an account/accounts/:id
  • PATCHChange how often X statistics are checked/accounts/:idX accounts only. X bills every statistics read, and OmniSocials passes X's price on as credits: a post check is half a credit (plus half a credit for a video…

Analytics

  • GETGet bulk post analytics/analytics/posts?ids=1024,1025,1026Batch version of GET /analytics/posts/{id}. Pass a comma-separated list of numeric OmniSocials post ids in ids and get each post's latest per-platform metrics…
  • GETGet post analytics/analytics/posts/:id
  • GETCompare tags/analytics/tagsHow each tag did against your normal, for the published posts in a period (the same table as the Tags tab in Analytics). vs_normal is fair across channels:…
  • GETGet analytics overview/analytics/overviewTotals for the workspace of this API key over a period (period, default 30 days, or start_date and end_date), with a breakdown per platform. Requires the…
  • GETGet account analytics/analytics/accountsLatest stored account-level snapshot per connected platform, on or before the requested date. Snapshots are collected daily. Metric semantics vary by platform…
  • GETGet best posting times/analytics/best-times?platform=instagramRecommended day/hour posting slots for one platform, computed from the workspace's own posting history (publish time × engagement of every post published on…
  • POSTCheck the X numbers of a post now ("Update now")/analytics/posts/:id/refreshReads the X statistics of one published post now, outside its schedule. X bills every read, so it costs half a credit per tweet (each part of a thread counts,…

Credits

  • GETCredit balance and X statistics/creditsThe organisation's credit balance (1 credit = €0.01), whether auto-refill is on, the credits used this month by type, and the X statistics overview: the state…

Approvals

  • GETList approval workflows/approval-workflowsSaved approval workflows the current workspace can use: company-wide workflows plus the ones bound to this workspace. Workflows are created and edited in the…

Webhooks

  • GETList webhooks/webhooksLists the webhooks of the key's workspace and the organisation-wide webhooks of its organisation (workspace_id null, made in the OmniSocials dashboard). The…
  • POSTCreate a webhook/webhooks
  • GETGet a webhook/webhooks/:idA webhook of the key's workspace or an organisation-wide webhook of its organisation.
  • DELETEDelete a webhook/webhooks/:idDeletes a webhook of the key's workspace or an organisation-wide webhook of its organisation.
  • PATCHUpdate a webhook/webhooks/:idWorks on a webhook of the key's workspace or an organisation-wide webhook of its organisation. Setting url or events, or switching the webhook on, makes the…
  • POSTRotate webhook secret/webhooks/:id/rotate-secretReturns a new signing secret, shown once. The old secret keeps signing for 24 hours: during that time every delivery carries X-OmniSocials-Signature (new…

Locations

  • GETSearch locations/locations/searchSearch physical places to get a valid location_id for tagging a post. The platform query parameter selects the source, and the two sources use DIFFERENT ids…
  • GETValidate a location/locations/validate?id=313813441Check whether a Facebook Place ID is a valid Instagram location (a single venue with a precise address) before using it as location_id. Returns { valid: true,…

Audio

  • GETSearch Instagram audio/audio/searchSearch Meta's licensed audio catalog for tracks that can be attached to an Instagram Reel. Pass a returned audio_id as instagram.audio_id on POST…

Pinterest

  • GETList product Pins/pinterest/productsList the product Pins of the connected Pinterest account. Pass a returned pin_id in pinterest.product_tags on POST /posts/create / PATCH /posts/{id} to tag…
  • GETCheck a product Pin/pinterest/products/validate?id=813744226420795884Check whether a Pin can be used in pinterest.product_tags before you create the post. Pass a Pin ID or a Pin link (https://www.pinterest.com/pin/<id>/; pin.it…

Inbox

  • GETList conversations/inbox/conversationsReturns one entry per conversation (the latest message in each), across Instagram and Facebook DMs, comments, and mentions, LinkedIn company-page comments and…
  • GETList messages/inbox/conversations/:conversationId/messagesReturns the full message history of a conversation, oldest first, cursor-paginated. Requires the inbox:read scope (API keys) or the access_social_inbox…
  • POSTMark conversation read/inbox/conversations/:conversationId/readMarks every unread incoming message in the conversation as read and returns how many were updated. Requires the inbox:write scope (API keys) or the…
  • POSTReply to a conversation/inbox/conversations/:conversationId/replySends a reply in an existing conversation (DM, comment, or mention) on Instagram, Facebook, LinkedIn, TikTok (comments only), YouTube (comments only), X…
  • POSTHide or unhide a comment/inbox/messages/:id/hideHides (or unhides) a comment someone left on one of your posts, on the platform, as the post owner. Facebook, Instagram, TikTok, YouTube and Threads comments…
  • POSTLike or unlike a comment/inbox/messages/:id/likeLikes (or removes the like from) a comment someone left on one of your posts, as the connected account: the Facebook Page, the LinkedIn Page or the TikTok…
  • DELETEDelete a comment/inbox/messages/:idDeletes a comment on one of your posts, on the platform and from the inbox: a comment someone left, or a reply your own account posted (direction: outgoing,…
  • GETGet next conversation/inbox/nextA work queue for answering the inbox. Returns one item that still needs a reply, together with its conversation so far and the post it belongs to, so a reply…

Automations

  • GETList automations/automationsReturns the comment-to-DM automations of the workspace, newest first. An automation answers a keyword in a comment (or a DM, or an Instagram story reply) with…
  • POSTCreate an automation/automationsCreates a comment-to-DM automation on the connected Instagram account (default) or on the connected Facebook Page (platform: facebook). When somebody comments…
  • GETGet an automation/automations/:id
  • DELETEDelete an automation/automations/:idDeletes the automation and its activity log. DMs that were already sent stay sent.
  • PATCHUpdate an automation/automations/:idPartial update. status pauses (paused) or resumes (active) the automation. trigger, actions and limits are merged into the stored sections: keys you omit keep…
  • GETList automation events/automations/:id/eventsOne row per comment or message the automation acted on, newest first: the DM that was sent, an answer that waits in the queue, a skip with its reason, or a…

Feature requests

  • GETList what OmniSocials cannot do/limitsThe things OmniSocials cannot do, why, and what to do instead: platform rules, features not built yet, features that work in the OmniSocials app only. Read it…
  • GETList your feature requests/feature-requestsThe feature requests of the person who owns the key (sent from the app, the MCP server, the API or the CLI), newest first, at most 50, with their status and…
  • POSTSend a feature request/feature-requestsSends a feature request to the OmniSocials team for the person who owns the key (their name and email are stored with it so the team can answer). Send it only…
  • GETGet a feature request/feature-requests/:idOne request of the person or their organisation, with its status and the team's replies.

API details

Base URL
https://api.omnisocials.com/v1
Authentication
A bearer token in the Authorization header
Operations
78 operations on 59 pathsGET 36POST 26PATCH 8DELETE 8
Main resources
Posts 12Media 11Inbox 8Analytics 7Automations 6Webhooks 6Hashtag Sets 5Tags 5Feature requests 4Folders 4
Response formats
application/json
Description format
OpenAPI 3.0.0, API version 1.0.0

How to test the OmniSocials API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the OmniSocials API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “List posts” (GET /posts), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the OmniSocials API?

The OmniSocials REST API schedules, publishes and analyzes posts on 13 social platforms. Upload media, receive webhooks and answer your social inbox. It… It is listed under Social and has 78 endpoints.

Who publishes the OmniSocials API?

It is listed from OmniSocials's public API description (an OpenAPI document), not published by OmniSocials on Swastik Codes. Anyone who controls omnisocials.com can claim the profile by adding a DNS TXT record.

What is the base URL of the OmniSocials API?

Requests go to https://api.omnisocials.com/v1. Endpoint paths are added to this base URL.

How do I authenticate with the OmniSocials API?

With A bearer token in the Authorization header.

How many endpoints does the OmniSocials API have?

78 operations on 59 paths (36 GET, 26 POST, 8 PATCH, 8 DELETE). The largest groups are Posts, Media, Inbox, Analytics.

Is forking the OmniSocials API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.