Schemas

Total number of items

Items per page

Number of items skipped

Whether there are more items

Post ID

Post type

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}.

Scheduled publish time (ISO 8601)

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)

Platform-specific error details (when status is failed or warning)

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.

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 account IDs to post to. Get IDs from GET /accounts

Post type: 'post' (feed), 'story' (Instagram/Facebook), 'reel' (Instagram/Facebook/YouTube/TikTok)

Media IDs from POST /media/upload. Flat array or per-platform object.

External image/video URLs to download and attach (max 10 total). Flat array or per-platform object. When using per-platform format, 'default' acts as fallback for selected platforms without their own key.

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.

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

TikTok options

X (Twitter) 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.

Media ID (use this in post creation)

CDN URL for the media

File size in bytes

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.

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

Event ID

Event type (e.g., post.published)

Event-specific data