Schemas

Total number of items

Items per page

Number of items skipped

Whether there are more items

Post ID

Post type. 'reel' media must be a video (MP4/MOV) — an image is rejected with 400 validation_error at schedule/publish; use 'post' to share an image.

Post content per platform

Account IDs to post to

Per-platform media object. Keys: default, instagram, facebook, etc. Each value is an array of {url, id, channel, alt?}.

Instagram location tag (Facebook Place/Page ID), echoed back from the create/update request. Omitted when not set.

Instagram co-author usernames (the 'Collab' feature), echoed back from the create/update request. Omitted when none set.

Instagram photo user tags, echoed back from the create/update request. Omitted when none set.

Scheduled publish time (ISO 8601)

Deep link to open this post inside the OmniSocials app, correct for the environment (staging vs production). Draft, scheduled, and failed posts open in the composer; published posts open in the details view. Hand this to the user so they can click straight through to review a draft you just created.

Live URLs of the post on each platform after publishing. Keys are platform identifiers (facebook, instagram, linkedin, linkedin_page, youtube, tiktok, pinterest, x, threads, bluesky, mastodon, google_business). Only platforms that successfully published appear; failed platforms are omitted (see errors). Empty object {} while the post is still draft, scheduled, or processing.

Approval workflow status (if applicable)

Per-platform user-friendly error messages, keyed by platform identifier (facebook, instagram, linkedin, linkedin_page, youtube, tiktok, pinterest, x, threads, bluesky, mastodon, google_business). Populated when status is failed or warning. Only platforms that failed appear; successful platforms are omitted (see published_urls). null while the post is still draft/scheduled/processing or every platform succeeded. Mirrors the per-platform error a user sees in the dashboard with a Retry button.

Origin of post creation: web, api, mcp, workflow, zapier, make, n8n, etc.

X (Twitter) options on the post. Includes per-publish settings (reply_settings, made_with_ai, paid_partnership) plus the canonical thread shape. Present when the post has X-specific data; omitted otherwise.

Bluesky options on the post. Present when the post is a Bluesky thread; omitted otherwise.

Mastodon options on the post. Present when the post is a Mastodon thread; omitted otherwise.

Instagram options on the post. Present when set; includes first_comment (the configured auto first comment) and, after publish, first_comment_result describing the outcome.

Facebook options on the post — first_comment and its post-publish first_comment_result.

LinkedIn Profile options on the post — first_comment and its post-publish first_comment_result.

LinkedIn Company Page options on the post — first_comment and its post-publish first_comment_result.

YouTube options on the post. After publish, first_comment and its first_comment_result are nested here alongside the Shorts metadata.

posted = comment is live; failed = the main post published but the comment did not (see error; retry via POST /posts/retry-first-comment); skipped = the main post did not publish so the comment was never attempted.

Post content. Use 'default' for all platforms, or platform-specific keys: instagram, facebook, linkedin, linkedin_page, youtube, tiktok, pinterest, x, threads, bluesky, mastodon, google_business. Coming soon: reddit, snapchat.

Social accounts to post to. Each entry is either:

• A bare platform name (e.g. "youtube", "linkedin_page"), or
• The composite ID returned by GET /v1/accounts in the form "<workspace_id>_<platform>" (e.g. "844008_youtube").

The composite form's workspace prefix must match the workspace your API key belongs to. Mismatched or unknown ids return 400 validation_error with an "Unknown account/platform" message — always source ids from GET /v1/accounts for the API key in use.

Post type: 'post' (feed), 'story' (Instagram/Facebook), 'reel' (Instagram/Facebook/YouTube/TikTok). A 'reel' must have video media (MP4/MOV); an image is rejected with 400 validation_error at schedule/publish — use 'post' to share an image.

Media IDs from POST /media/upload. Flat array or per-platform object. Any entry may be an { id, alt } object to carry a per-media accessibility description (alt text, max 1500 chars).

External image/video/PDF URLs to download and attach (max 10 total, each file ≤ 100 MB). Flat array or per-platform object. Any entry may be a { url, alt } object to carry a per-media accessibility description (alt text, max 1500 chars) — delivered to Mastodon, Bluesky, X and Pinterest. When using per-platform format, 'default' acts as fallback for selected platforms without their own key. A PDF URL is rasterized into one image slide per page (max 20, in order) — on LinkedIn it publishes as a swipeable document, elsewhere as an image carousel; slides inherit the entry's alt. For files over 100 MB (up to 1 GB), upload first via POST /v1/media/upload-from-url and attach the returned media id via the media field; oversized media_urls fail with code file_too_large.

ISO 8601 datetime to schedule. Omit for draft.

Set true to publish immediately

URL to share as a rich preview card on platforms that support link-share posts (currently LinkedIn and Facebook). When set on a text post, the URL renders as a preview tile with thumbnail / title / description instead of plain text. Ignored on platforms that don't support link shares (Instagram, TikTok, etc.) and on posts that already have media attached — media takes precedence.

Optional title for the link-share preview. LinkedIn uses this directly when set. Facebook ignores this — it fetches OG metadata server-side. Omit to let LinkedIn auto-fetch the page title.

Optional description for the link-share preview. LinkedIn uses this when set; Facebook auto-fetches the OG description. Omit to defer to OG metadata.

Optional thumbnail image URL for the preview card. Currently not yet applied to LinkedIn (would require uploading to LinkedIn's image API first); included for forward compatibility.

Self-reported origin of the integration creating this post. Defaults to 'api' if omitted. Use 'zapier', 'make', 'n8n', etc. to identify your integration.

Instagram only. Facebook Place/Page ID to tag the post's location with (e.g. a dealership or storefront). Applied to single-image and carousel feed posts via Instagram's content-publishing location_id. Find a Place's Page ID via Facebook's Pages Search API. Ignored by other platforms. Send an empty string on PATCH to clear it.

Instagram only. Up to 3 public Instagram usernames to invite as co-authors (the 'Collab' feature). Applied to image, carousel, and reel posts — NOT Stories. Invited users get an invitation in the Instagram app; once accepted, the post also appears on their profile and feed. Usernames are case-insensitive and a leading '@' is stripped. Private accounts and non-existent usernames are rejected by Instagram at publish time. Ignored by other platforms. Send an empty array on PATCH to clear collaborators.

Instagram only. Tag public Instagram accounts at specific positions on a photo. Photos only — NOT video, reels, or stories. For a single image omit image_index (or set 0); for a carousel, set image_index to the 0-based slide the tag belongs to (tags attach to that slide's image). Public accounts only; private/non-existent usernames are rejected by Instagram at publish time. Ignored by other platforms. Send an empty array on PATCH to clear tags.

Name of a saved hashtag set (see GET /hashtag-sets) to apply to this post, matched case-insensitively. The set's tags are merged in ONCE at create time — the post stores plain text, so later edits to the set never change this post. Tags already present in a caption are skipped (case-insensitive), and hard platform caps (Instagram 30) are enforced with a 400 hashtag_limit_exceeded before the platform can reject the post. Mutually interchangeable with hashtag_set_id.

Id of a saved hashtag set to apply. Same behavior as hashtag_set; pass one or the other.

Where the set's tags land. caption_append (default) appends them to each target platform's caption after a blank line. first_comment puts them in the auto first comment on comment-capable platforms (Instagram, Facebook, LinkedIn Profile/Page, YouTube) — appended after any first_comment you passed explicitly — and falls back to caption_append on platforms without a comment API. Stories always use captions (first comments are never posted on Stories).

Optional subset of the post's selected platforms to apply the set to (e.g. only ["instagram", "tiktok"]). Defaults to all selected platforms.

Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or the flat media_urls) to publish a single carousel pin; the title, description, link, and alt_text apply to the whole pin. A single image or a single video still publishes as a normal image / video pin. Carousel constraint: Pinterest's v5 API requires every slide in a carousel pin to share the same aspect ratio (1% tolerance). If you attach mixed-ratio images and try to schedule or publish, the API responds 400 validation_error with mismatched_slides: [n, ...] listing the 1-indexed slide numbers that need to be re-cropped or removed. The check is run when publish_now: true, when schedule_at is set, and when PATCH flips a draft to a scheduled status — drafts are exempt so you can iterate on media.

YouTube Shorts options. Only applies when type is reel and youtube is among the selected accounts.

Instagram Reel options

Facebook options

LinkedIn Profile options

LinkedIn Company Page options

TikTok options

X (Twitter) options

Bluesky options

Mastodon options

Google Business Profile options. Use to publish EVENT or OFFER posts in addition to STANDARD, attach a call-to-action button, or both. STANDARD posts can also use this object purely to add a CTA. The shape mirrors Google's LocalPost JSONB exactly; see https://developers.google.com/my-business/reference/rest/v4/accounts.locations.localPosts#LocalPost.

Caption rules (enforced at scheduling — text that violates these returns validation_error 400 before the post is saved): • No phone numbers in the caption (use a CALL button instead). • No inline URLs / bare domains / email addresses (use a LEARN_MORE, BOOK, SHOP, SIGN_UP, or ORDER button instead). • Caption max 1500 characters. • Media optional (text-only posts allowed). If attached: exactly one JPEG/PNG/WebP image (no video, no carousels). • The workspace must have a Google Business location selected (Settings → Organisation → Workspaces → Google Business) before scheduling.

Media ID (use this in post creation)

Permanent CDN URL for the media

CDN URL of the generated preview thumbnail (videos only; null for images, which use url directly)

Human-readable label set on upload or via PATCH (e.g. "pp-play5get50"). Falls back to the storage filename when unset. Search this with the search query param.

Id of the folder this file lives in, or null for the root ("All media")

Generated storage filename (stable, used internally)

Human-formatted file size (e.g. "2.50 MB")

Processing state. 'ready' for normal uploads (usable immediately). Large videos uploaded via URL ingestion (over 100 MB) start as 'processing' — poll get media / list media until 'ready' before using them in a post. 'failed' means the source couldn't be fetched or validated.

One-line human summary, or null when fully compatible.

Every page as a Media item, in page order.

Slide ids in page order — pass all of them to POST /posts.

Whether the file fits the platforms connected to your workspace. compatible is true when no connected platform would reject it.

Parent folder id, or null for a top-level folder

Number of media items directly in this folder

Set name, unique per workspace (case-insensitive)

Ordered tags WITHOUT the leading '#'

The tags rendered as caption text, e.g. "#fitness

Account ID (use this when creating posts)

Social media username/handle

Display name on the platform

Profile picture URL

Supported content types for this platform

Connection status. needs_reconnect means the account is still wired up to the workspace but its OAuth token has been revoked or expired; posts to this account will fail until the user reconnects in the OmniSocials UI. Most often caused by the user changing their password, deauthorizing OmniSocials on the platform, or the token expiring without a successful refresh.

Convenience boolean — true when status is needs_reconnect.

Short reason from the platform (e.g. "OAuthException: Session has expired"). Present only when needs_reconnect is true. Token-health tracking exists for Instagram, Facebook, Threads, X, Pinterest, LinkedIn (profile + page); other platforms always report needs_reconnect: false.

Pinterest boards (only present for Pinterest accounts). Use board id as board_id when creating Pinterest posts.

Platform-specific details. Present for X accounts with Premium subscription.

One entry per platform the post was published to. For thread platforms (X, Bluesky, Mastodon) a post can publish as a chain of several parts; the entry sums each part's metrics so you get the thread's total (matching the in-app analytics), and reports the thread's root as platform_post_id.

Engagement rate as a percentage (0-100)

Platform-specific account metrics (followers, impressions, profile_views, etc.)

URL to receive webhook events

Events to subscribe to

Consecutive delivery failures since the last success. Resets to 0 on any successful delivery, so 0 means currently healthy.

Details of the most recent failed delivery. Not cleared on success, so it persists as the last known problem even when failure_count is 0. Null if no delivery has ever failed.

Unique delivery event ID (also sent as the X-OmniSocials-Delivery header)

Event type

Event payload

Platform-scoped id of the other party

dm = direct message; comment/mention = public interaction. LinkedIn is comment/mention only.

Unread incoming messages in this conversation

Present for comment/mention conversations

Pass as ?cursor= to fetch the next page; null when there are no more results