Core Concepts

A handful of objects make up the whole API.

Connected accounts

A connected account is a social profile you've authorized — an X handle, a LinkedIn profile or Page, etc. Each has an id, a platform, and an is_active flag. You publish to connected accounts; their ids are what you pass to social_account_ids when creating a post. Accounts are connected from the dashboard under Settings → Connected Accounts.

Posts

A post is one piece of content targeted at one or more connected accounts. A post moves through a lifecycle:

Status	Meaning
draft	Saved but not scheduled.
scheduled	Queued to publish at scheduled_at.
published	Sent to the platforms.
failed	Publishing failed (see error_message).

Publish immediately by omitting scheduled_at and setting publish_now: true. Otherwise set a future scheduled_at (ISO 8601, UTC recommended).

Per-account delivery

Because one post can target several platforms, each post carries a per-account delivery record (the pivot on socialAccounts) with its own status (pending, published, failed), the resulting platform_post_id, and the public platform_url. One platform can succeed while another fails.

Per-platform content

By default every targeted account gets the same content. To tailor the text per platform (e.g. a short version for X, a longer one for LinkedIn), pass platform_content — an array mapping account_id to custom content. See Posts.

Media library

The media library holds images and video you upload once and reuse across posts. Upload returns a media object with an id; attach media to a post by passing media_ids. Manage media via Media, or over MCP with browse_media and upload_media.

Putting it together

1. Connect accounts (dashboard) → get account ids.
2. Optionally upload media → get media ids.
3. Create a post with content, social_account_ids, and optional media_ids / scheduled_at.
4. Read back the post to see per-account delivery status.