walid@portfolio:~/lab/omnisocials-api$
cd../lab
43ideaSep 2026

One key, twelve channels

Publishing to eleven social platforms from a single REST call — and the two costs that sit outside the flat monthly price

One POST replaces eleven platform APIs, each with its own OAuth flow, media rules and idea of what counts as a video. The scheduling call is the easy part — four lines. The parts worth knowing before you build on it are the two costs that sit outside the flat monthly price, and the fact that the field names in the curl examples are not the field names the SDKs put on the wire.

REST APISocial automationMCPSchedulingSDKsThe docs ↗OpenAPI spec ↗MCP server ↗
i
What it actually collapses

Posting one thing to Instagram, LinkedIn, X and TikTok by hand means four APIs, four OAuth flows, four media specs and four sets of rules about file size and duration. This puts a single REST endpoint in front of all of them: send content, a list of target channels and optional media, and it fans out. Connecting the accounts stays manual and one-time — OAuth happens in the dashboard and cannot be done through the API — but after that every key in the workspace can publish to them.

Checked, not copied

The numbers, verified on 18 September 2026

Read off the published OpenAPI schema, the package registries and the pricing page rather than taken from the write-up.

ClaimWhat the primary source says
Channels12 channels across 11 platforms — LinkedIn counts twice, as a personal profile and a company page. Both numbers get quoted; they are counting different things.
Rate limit100 requests per minute per API key, on a rolling 60-second window, returning X-RateLimit-Remaining and a Retry-After. Enforced per key rather than per workspace, and the docs name splitting work across several keys as a supported way to scale.
Price$10 per workspace per month at the annual rate, billed $120 a year. The page advertises $24 a year off annual versus monthly, which puts month-to-month at $12.
Seats$10 per seat. Team members and additional workspaces are add-ons on top of the base plan, not included in it.
SDKsEight languages documented, seven installable. Java has no artifact on Maven Central under com.omnisocials or io.omnisocials.
Versions0.6.0 on npm, PyPI, crates.io, RubyGems and NuGet, all published 17 September 2026. MIT.
Free credits200 per organisation at signup, which is the currency for the metered X actions further down.
Step 1

Create the account

Fourteen-day trial, then $10 a month per workspace on annual billing. Seats and extra workspaces are $10 each on top — the API itself is not gated behind a sales call.

Step 2

Connect the accounts

Settings → Connect on each platform. Two clicks each: sign in, approve. This is the one part with no API equivalent.

Step 2

What you can connect

Twelve rows, eleven platforms — LinkedIn appears twice because a personal profile and a company page are separate connections with separate options.

CategoryPlatforms
CoreInstagram, Facebook (+ Reels), X, TikTok
ProfessionalLinkedIn Profile, LinkedIn Company Page, YouTube, Google Business
DecentralizedBluesky, Threads, Mastodon
VisualPinterest
Step 3

Create the key

Settings → Organisation → API → Create key.

!
Shown once, and the inbox scopes are off by default

Keys read omsk_live_… against real accounts or omsk_test_… for a sandbox that touches nothing, and the value is displayed exactly once. The two inbox scopes are opt-in: a key created without them returns 403 the first time it reads a DM, which looks like a broken key rather than an unticked box. Scopes cannot be added to an existing key — a key that needs them has to be replaced.

Step 3

The full scope list, which is longer than most walkthroughs mention

✓posts:read and posts:write — read, create, schedule and update posts✓media:write — upload into the media library✓accounts:read — list the connected channels and their ids✓analytics:read — per-post and per-account numbers✓webhooks:manage — register and rotate webhook endpoints✓inbox:read and inbox:write — opt-in, and off unless ticked at creation
Step 3

Keep it out of the code

env.sh1 lines
export OMNISOCIALS_API_KEY="omsk_live_..."
Step 3

Every call uses this header

header.txt1 lines
Authorization: Bearer $OMNISOCIALS_API_KEY
Step 4

Schedule a post

content and accounts are the only required fields. Everything else is optional.

create-post.sh9 lines
curl -X POST https://api.omnisocials.com/v1/posts/create   -H "Authorization: Bearer $OMNISOCIALS_API_KEY"   -H "Content-Type: application/json"   -d '{
    "content": {
      "default": "Shipped a new feature today.",
      "instagram": "Shipped something new today."
    },
    "accounts": ["linkedin", "x", "threads"],
    "media_urls": ["https://yoursite.com/screenshot.png"],
    "schedule_at": "2026-10-01T09:00:00Z"
  }'
Step 4

The fields that matter

content takes a plain string when every platform gets the same caption, or an object keyed by platform with a default fallback. The object form is the documented one, and it is the actual argument for routing through one API instead of four — the same post, phrased for each audience, in one call.

accounts takes either a bare platform name or the composite <workspace_id>_<platform> id returned by GET /v1/accounts. The workspace prefix has to match the workspace the key belongs to; a mismatch comes back as a 400 naming the unknown account rather than quietly skipping that target.

Drop schedule_at and the post is saved as a draft. Add "publish_now": true to send it straight away, or POST to /v1/posts/:id/publish afterwards. media_urls takes public URLs the API downloads for you — up to 10 files, 100 MB each. To upload a local file instead, POST it to /v1/media/upload first (multipart, field name file) and pass the returned id in media.

!
The field names change the moment you pick up an SDK

The curl examples and the OpenAPI schema use accounts, schedule_at and media. Every SDK sends channels, scheduled_at and media_ids instead. This is not one library drifting — the Go and Python clients, written separately, both do it, and both decode the documented names on the way back. So it reads as a genuine alias set rather than a bug. I could not exercise both spellings against a live key, so treat the mapping as observed from two shipped clients rather than confirmed end to end; the practical point stands either way, which is that a payload copied between the docs and an SDK issue will not line up field for field.

The same fields, under two names

Raw HTTP / OpenAPIEvery SDKWhat it is
accountsEvery SDKchannelsWhat it isthe target platforms
schedule_atEvery SDKscheduled_atWhat it isISO 8601 publish time; omit for a draft
mediaEvery SDKmedia_idsWhat it isids returned by /media/upload
media_urlsEvery SDKmedia_urlsWhat it ispublic URLs the API fetches — the one name that matches
Step 5

How a post performed

analytics-one.sh1 lines
curl https://api.omnisocials.com/v1/analytics/posts/59546574   -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
Step 5

Up to 100 ids in one call

The batch endpoint exists precisely so a sync job does not spend its 100-a-minute budget one post at a time.

analytics-batch.sh1 lines
curl "https://api.omnisocials.com/v1/analytics/posts?ids=59546574,59546590"   -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
Step 5

Account-level numbers, not tied to a post

analytics-accounts.sh1 lines
curl https://api.omnisocials.com/v1/analytics/accounts   -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
Step 6

The social inbox

Every DM, comment and mention across every connected platform in one thread. Needs inbox:read and inbox:write.

inbox-list.sh1 lines
curl https://api.omnisocials.com/v1/inbox/conversations   -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
Step 6

Read a thread, and reply to it

inbox-reply.sh3 lines
curl https://api.omnisocials.com/v1/inbox/conversations/CONVERSATION_ID/messages   -H "Authorization: Bearer $OMNISOCIALS_API_KEY"

curl -X POST https://api.omnisocials.com/v1/inbox/conversations/CONVERSATION_ID/reply   -H "Authorization: Bearer $OMNISOCIALS_API_KEY"   -H "Content-Type: application/json"   -d '{"text": "Thanks for reaching out."}'
!
The flat price is not the whole bill, if you post links to X

X bills developers roughly thirteen times more for a post whose text contains a URL ($0.20 against $0.015), and that is passed through at cost as prepaid credits: 20 credits for a link post, 1 credit to receive an X DM, 2 to reply. Credits are €0.01 each, topped up in €5–500 blocks, and every organisation starts with 200 free. A scheduled X link post reserves its cost until it publishes, and one that would push the reserved total past the balance is refused up front with 402 x_credits_insufficient. If the balance runs dry at publish time the X target alone fails and the rest of the post still goes out. Everything else — X posts without links, every other platform, scheduling, analytics, the inbox — stays free and unlimited. Worth knowing before pointing a release-notes automation at X.

SDKs

Or skip the raw HTTP

Same shape in every language: client.posts.create(...), typed requests and responses, retries, and a webhook signature helper.

SDKs

Eight documented, seven you can install today

Each one checked against its registry on 18 September 2026.

LanguageInstallState
Node / TypeScriptInstallnpm install @omnisocials/sdkState0.6.0, MIT
PythonInstallpip install omnisocialsState0.6.0
GoInstallgo get github.com/OmniSocials/omnisocials-goStateMIT, needs Go 1.26
RubyInstallgem install omnisocialsState0.6.0
PHPInstallcomposer require omnisocials/omnisocials-phpStateon Packagist
.NETInstalldotnet add package OmniSocialsState0.6.0 on NuGet
RustInstallcargo add omnisocialsState0.6.0
JavaInstallMaven / GradleStatenot published — nothing on Maven Central
Not in the write-up

There is also an MCP server

The guide never mentions it, but the same API ships as an MCP server, which is the more interesting door for anyone already driving work from an assistant. It honours the same scopes as the REST API, so the key decides what the assistant may do — a read-only key is a genuinely safe way to let a model look at your analytics without giving it the ability to post anything.

Published as @omnisocials/mcp-server, MIT, at 1.35.0 as of 15 September 2026.

MCP

Wiring it up

mcp.sh3 lines
claude mcp add omnisocials -- npx -y @omnisocials/mcp-server

export OMNISOCIALS_API_KEY=omsk_live_...
The rest of the surface

Resources the guide leaves out, all present in the clients

✓Approval workflows — route a scheduled post through named approvers before it publishes✓Hashtag sets — save a group of tags once and apply them at create time, appended or as a first comment✓Webhooks — a signed event pushed to you instead of polling analytics✓Folders and locations — organise the media library, and tag Instagram posts with a Facebook Place✓Audio — the media library handles sound, not only images and video✓Video covers — pick a frame or supply a custom thumbnail, with per-platform overrides
Before you build on it

The limits that actually bite

✗Inbox replies cap at 1,000 per rolling 24 hours per workspace, then 429 reply_limit_reached✗Uploads are capped at 100 MB whatever the destination platform allows — bigger files have to go through the URL-ingest path✗X, Bluesky and Mastodon take at most 4 images and refuse to mix images with video; Instagram and Threads take 10 and will mix✗Video duration is validated at submit, not at publish: YouTube Shorts 3 min, Facebook Reels 90 s, X 140 s on the free tier✗Connecting a social account has no API at all — it is OAuth in the dashboard, once per platform✗It does not write captions or decide a schedule. It is transport, not a content tool.
If it does not work

Almost always one of these

✗401 on every call — the key was truncated on copy, or the header is missing the Bearer prefix✗403 on inbox calls only — the key lacks inbox:read / inbox:write, which are off by default✗400 naming an unknown account — a composite id from a different workspace than the key belongs to✗Accepted but never appears — the platform is not connected, or the name passed in accounts is wrong✗429 — read X-RateLimit-Remaining, then back off for the Retry-After value in seconds
The result

One key, four calls

← previous
Fifty sites, and the seven you will actually use
next →
A shorts studio that runs in the terminal
← all experiments