Glossary of OmniSocials API terms
The terms you meet in these docs, grouped by topic. Each entry names the field or endpoint it maps to and links to the page that covers it in full.
Access and billing
Organisation. The top-level OmniSocials account that holds your workspaces, team members, billing and credits. It is managed in the dashboard under Settings → Organisation; the API has no organisation endpoint. See Billing.
Workspace. One set of connected social accounts, typically one brand or one client. Every API key belongs to one workspace, and GET /accounts returns its workspace_id and workspace_name. See Authentication.
Seat. A team member on the organisation's plan, billed as its own line item next to the workspaces. The organisation owner does not use a seat. See Pricing.
API key. A long-lived token created under Settings → API, always starting with omsk_live_. Send it on every request as Authorization: Bearer omsk_live_.... See Authentication.
Scope. A permission on an API key, such as posts:write or analytics:read. A request without the needed scope returns 403, and the inbox and automation scopes are opt-in when you create the key. See Scopes.
Rate limit. 100 requests per minute per API key, on a rolling 60 second window. Over the limit the API answers 429 rate_limit_exceeded with a Retry-After header. See Rate limits and errors.
Credits. A prepaid balance on the organisation, used only for X posts that contain a link (20 credits each) and for opt-in X DMs. A short balance returns 402 x_credits_insufficient; credits are topped up in the dashboard. See Billing.
Channels and accounts
Platform. A social network, such as Instagram or LinkedIn. OmniSocials supports 12 platforms. See Platforms.
Channel. A posting target with a stable string ID, such as instagram or linkedin_page. There are 13 channels, because LinkedIn counts twice: linkedin for a profile and linkedin_page for a company page. See How channel IDs are used.
Account. One connected profile, page or chat in a workspace, listed by GET /accounts. Its id (for example 368204_instagram) goes in a post's accounts array, and accounts are connected in the dashboard, never through the API. See Connecting accounts.
needs_reconnect. A flag on an account in GET /accounts: its connection was revoked or expired, and posts to it fail until someone reconnects it in the dashboard. reauth_reason carries the platform's reason. See Known issues.
Posts
Post. The core resource: text, media and options for one or more accounts, created with POST /posts/create. See Posts.
Post type. The type field: post (a feed post, the default), story or reel. Stories and reels need media. See Post types.
Draft. A post with status: "draft". Every post is a draft unless the request has publish_now or schedule_at, and a draft never publishes on its own. See Posts.
Planned draft. A draft that keeps a time: draft: true together with schedule_at. It shows on the dashboard calendar but never publishes until someone schedules it. See Planned drafts.
Scheduled post. A post with schedule_at set to a future ISO 8601 time in UTC. It has status: "scheduled" and publishes within a 1 minute window of that time. See Scheduling.
publish_now. "publish_now": true on POST /posts/create publishes right away; POST /posts/create-and-publish is the same call. The response has status: "posting", so poll GET /posts/:id for the outcome. See Publishing.
Post status. The status field: draft, in_approval, rejected, scheduled, posting, published, warning or failed. warning means some channels published and others failed. See Post statuses.
Carousel. One feed post with several media items, passed as 2 or more entries in media_ids or media_urls. Each channel publishes it its own way, for example a carousel of up to 10 items on Instagram, a document carousel on LinkedIn, or a carousel pin of 2 to 5 images on Pinterest. See Capability matrix.
Story. type: "story": a 24 hour post on Instagram or Facebook. Up to 10 media items, each published as its own story, and no caption on the story itself. See Stories.
Reel. type: "reel": one vertical video, published as an Instagram or Facebook Reel, a YouTube Short or a TikTok video. Telegram sends it as a video message. See Reels.
Thread. thread_parts under x, bluesky, mastodon or threads: 2 to 25 parts, each published as a reply to the one before. See X threads.
Poll. poll under the x, threads, mastodon or telegram key, where the post text is the question. LinkedIn polls use the top-level linkedin_poll field. See Polls.
First comment. first_comment under a channel's key (Instagram, Facebook, LinkedIn, YouTube, TikTok and Telegram): a comment posted right after the post publishes. The outcome comes back as first_comment_result. See Automatic first comment.
Hashtag set. A named group of hashtags, managed with /hashtag-sets and applied with hashtag_set (or hashtag_set_id) when you create a post. The tags are merged into the text once, so editing the set later never changes existing posts. See Hashtag sets.
Approval workflow. A chain of review steps and approvers, set up in the dashboard. Pass its id as approval_workflow_id with schedule_at, and the post waits as in_approval until the last step approves it. See Approval workflows.
Retry. POST /posts/:id/retry publishes the failed channels of a failed or warning post again, on the same post. Each channel can be retried 3 times. See Retries and duplicate posts.
Native post ID. The platform's own id of a published post, such as an Instagram media id or a tweet id. Webhooks carry it as data.targets[].native_post_id, and the live links are in published_urls on the post. See Webhooks.
Media
Media item. A file in the workspace's media library (an image, a video or a PDF) with an id. Create one with POST /media/upload or POST /media/upload-from-url. See Media.
media_ids and media_urls. The two ways to attach media to a post: media_ids takes library ids, and media_urls takes public URLs that the API downloads (up to 10, 100 MB each). Both accept a flat array or an object keyed by channel ID. See Attaching media.
Alt text. An accessibility description per media item, passed as { "url": "...", "alt": "..." } or { "id": "...", "alt": "..." }. It is delivered to the platforms that support it, up to 1500 characters. See Alt text.
Inbox and automations
Inbox conversation. A DM thread, or all comments or mentions on one post, with an opaque conversation_id that you URL-encode in paths. List them with GET /inbox/conversations, which needs the opt-in inbox:read scope. See Social inbox.
Work queue. GET /inbox/next: the one conversation that should be answered next, with its messages and post. Reply with include_next: true to get the following item in the same response. See Working through the inbox.
Automation (comment-to-DM). An Instagram rule that sends a DM to everyone who comments a keyword (or sends it in a DM or a story reply), once per person. Manage it with /automations or comment_dm_automation on a post; it needs the opt-in automations:write scope. See Automations.
Webhooks and tools
Webhook. A public HTTPS endpoint you register with POST /webhooks to receive signed POST requests for five post events. It needs the webhooks:manage scope. See Webhooks.
Webhook secret. The 64 character hex secret returned once when you create a webhook. It signs every delivery (HMAC-SHA256, in X-OmniSocials-Signature) and is replaced with POST /webhooks/:id/rotate-secret. See Verifying signatures.
MCP server. OmniSocials' Model Context Protocol server, hosted at https://mcp.omnisocials.com or run locally with npx -y @omnisocials/mcp-server. It exposes the API as tools, such as create_post, for AI assistants. See MCP server.
CLI. omnisocials, a single-file Node.js command line tool that covers the v1 API, with --json output on every command. See CLI.
Agent skill. The OmniSocials skill for coding agents, installed with npx skills add OmniSocials/omnisocials-agent-skills: a SKILL.md instruction file plus the CLI. It suits agents that can run shell commands but have no MCP support. See Agent Skills.
SDK. An official client library for the API, available for Node, Python, Go, Ruby, PHP, Java, .NET and Rust. See SDKs.
OpenAPI file. The machine-readable spec of every endpoint, at docs.omnisocials.com/openapi.json. The API reference is generated from it.