# Glossary of OmniSocials API terms

> Index of all OmniSocials docs pages: https://docs.omnisocials.com/llms.txt

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](https://docs.omnisocials.com/billing.md).

**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](https://docs.omnisocials.com/authentication.md).

**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](https://docs.omnisocials.com/pricing.md#team-members).

**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](https://docs.omnisocials.com/authentication.md).

**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](https://docs.omnisocials.com/authentication.md#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](https://docs.omnisocials.com/rate-limits-and-errors.md).

**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](https://docs.omnisocials.com/billing.md#credits-and-x-link-posts).

## Channels and accounts

**Platform.** A social network, such as Instagram or LinkedIn. OmniSocials supports 12 platforms. See [Platforms](https://docs.omnisocials.com/platforms.md).

**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](https://docs.omnisocials.com/platforms.md#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](https://docs.omnisocials.com/platforms.md#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](https://docs.omnisocials.com/known-issues.md).

## Posts

**Post.** The core resource: text, media and options for one or more accounts, created with `POST /posts/create`. See [Posts](https://docs.omnisocials.com/creating-posts.md).

**Post type.** The `type` field: `post` (a feed post, the default), `story` or `reel`. Stories and reels need media. See [Post types](https://docs.omnisocials.com/creating-posts.md#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](https://docs.omnisocials.com/creating-posts.md#minimal-request).

**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](https://docs.omnisocials.com/creating-posts.md#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](https://docs.omnisocials.com/creating-posts.md#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](https://docs.omnisocials.com/creating-posts.md#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](https://docs.omnisocials.com/creating-posts.md#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](https://docs.omnisocials.com/platforms.md#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](https://docs.omnisocials.com/creating-stories.md).

**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](https://docs.omnisocials.com/creating-reels.md).

**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](https://docs.omnisocials.com/platforms/x.md#posting-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](https://docs.omnisocials.com/creating-posts.md#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](https://docs.omnisocials.com/creating-posts.md#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](https://docs.omnisocials.com/creating-posts.md#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](https://docs.omnisocials.com/creating-posts.md#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](https://docs.omnisocials.com/retries.md).

**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](https://docs.omnisocials.com/webhooks.md#payload-shape).

## 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](https://docs.omnisocials.com/media.md).

**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](https://docs.omnisocials.com/creating-posts.md#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](https://docs.omnisocials.com/creating-posts.md#alt-text-accessibility-descriptions).

## 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](https://docs.omnisocials.com/inbox.md).

**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](https://docs.omnisocials.com/inbox.md#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](https://docs.omnisocials.com/automations.md).

## 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](https://docs.omnisocials.com/webhooks.md).

**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](https://docs.omnisocials.com/webhooks.md#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](https://docs.omnisocials.com/mcp-server.md).

**CLI.** `omnisocials`, a single-file Node.js command line tool that covers the v1 API, with `--json` output on every command. See [CLI](https://docs.omnisocials.com/cli.md).

**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](https://docs.omnisocials.com/integrations/agent-skills.md).

**SDK.** An official client library for the API, available for Node, Python, Go, Ruby, PHP, Java, .NET and Rust. See [SDKs](https://docs.omnisocials.com/sdks.md).

**OpenAPI file.** The machine-readable spec of every endpoint, at [docs.omnisocials.com/openapi.json](https://docs.omnisocials.com/openapi.json). The [API reference](https://docs.omnisocials.com/api) is generated from it.