Quickstart: publish your first post
OmniSocials is an API for scheduling and publishing social media posts across 14 channels (13 platforms, with LinkedIn split into a personal profile and a company page) from a single endpoint. This guide gets you from zero to your first published post in five steps, in about five minutes.
Using a coding agent?
Give it this prompt. It reads the markdown version of this page.
Before you start
- An OmniSocials account.
- One social account connected to it. You connect it once in the dashboard (step 3). It cannot be done through the API.
- An API key with the scopes
posts:write,media:writeandaccounts:read(step 1).
The examples use curl, the Node.js SDK (npm install @omnisocials/sdk) and the Python SDK (pip install omnisocials). Pick a tab and every step follows it.
1. Create an API key
Sign in to app.omnisocials.com, open Settings → API, and click Create API Key.
Pick the scopes your integration needs. For most use cases, start with posts:write, media:write, and accounts:read. A key's scopes cannot be edited afterwards; when you need more, create a new key.
Copy the key and store it somewhere safe. Keys start with omsk_live_ and work on your real connected accounts; there is no separate test mode.
Terminal
2. Verify access
Every request authenticates with a Bearer token in the Authorization header. The easiest way to check the key works is to list your connected accounts. The SDKs read OMNISOCIALS_API_KEY from the environment and send the header for you.
A 200 response with a data array (plus workspace_id and workspace_name) means you're in. If you see 401, the key is wrong. If you see 403, the key is missing the accounts:read scope.
3. Connect a social account
You cannot connect social accounts through the API. Accounts are connected once through OAuth in the OmniSocials dashboard, and then become available to every API key in the workspace.
Open Settings → Organisation → Workspaces, choose the workspace, pick the platform you want, and complete the OAuth flow. Re-run the GET /accounts call from step 2 to confirm the account appears in the list. Copy its id for the next step.
4. Upload media (optional)
Text-only posts skip this step. Platforms that require media (Instagram, TikTok, Pinterest, stories, reels) need a media file or URL.
Response:
JSON
Save data.id for the next step.
Alternatively, skip the upload step entirely and pass external URLs directly in media_urls on the post. The API downloads and attaches them for you. See Media for the full reference.
5. Create your first post
Use the account id from step 3 and, optionally, the media id from step 4 in media_ids.
The SDKs call the accounts field channels and the schedule time scheduled_at, where the REST examples use accounts and schedule_at. The API accepts both names, and content can be a plain string or an object with a default key.
A successful response is a 201 with the new post record:
JSON
In responses, accounts is a map of every platform key to true or false; the channels the post targets are true. The example above is shortened.
The post is saved as a draft. To publish immediately instead, add "publish_now": true to the body above, or POST to /v1/posts/:id/publish afterwards. /v1/posts/create-and-publish is an equivalent alias for the publish_now variant. In the SDKs, call posts.createAndPublish() (Node.js) or posts.create_and_publish() (Python) with the same fields, or posts.publish(id) afterwards. After publishing, poll GET /v1/posts/1024 (posts.get(id) in the SDKs) until status is published; the live links appear in published_urls.
If the call fails: 401 means the key is wrong, 403 means a missing scope, and 400 returns an error.message that names the exact problem. See Rate limits and errors.
Next steps
- SDKs wrap this API in 8 languages (Node, Python, Go, Ruby, PHP, Java, .NET, Rust) so you skip the raw HTTP
- Creating posts covers scheduling, per-platform content, post types, and updates
- Cross-posting covers publishing the same post to many platforms at once (the reason to use OmniSocials instead of calling every platform's API directly)
- Media covers upload methods, formats, and size limits
- Platforms lists channel IDs and platform-specific options
- Rate limits and errors lists the limits and status codes you need to handle
- API reference is the full endpoint spec generated from the OpenAPI schema