Creates one post per target entry. A single call can fan out an upload to multiple platforms; you'll receive one post object per target back, each with its own status that progresses asynchronously.

Publish modes

• immediate - publish as soon as processing finishes
• scheduled - publish at scheduled_for (top-level or per-target)
• draft - save without publishing; can be promoted via PATCH /posts/{id}

Captions and copy

Top-level caption is the default for every non-YouTube target; per-target caption overrides it. first_comment works the same way: top-level is the default, per-target overrides. YouTube targets ignore caption — they read per-target title and description instead (no top-level title/description; use target.title / target.description if you need them set).

Platform-specific fields like TikTok privacy levels live under target.platform_options.

Workspace defaults

Anything you leave out of top-level caption / first_comment, per-target caption / title / description / first_comment, or target.platform_options falls back to the workspace's saved preferences. This keeps API-created posts in the same "complete settings" state the dashboard would produce.

Precedence, highest to lowest:

1. target.<field> and target.platform_options.<platform>.<field>
2. Top-level caption / first_comment
3. Workspace preferences for this workspace
4. Field stays unset (publish will fail later if the platform requires it)

Workspace defaults that get applied today include YouTube privacy_status / notify_subscribers / category_id / default_language / playlist_ids / tags / upload_early_for_review, TikTok privacy_level / is_aigc / post_mode, Instagram share_to_story / collaborators / user_tags / prepend_audio_to_caption, Facebook share_to_story, LinkedIn visibility, Discord silent / mention / username / threadName, plus the top-level caption / first_comment and the YouTube-only title / description. To intentionally publish without a workspace default, send the field explicitly with the value you want (an empty string clears text fields).

Partial failure

Request-shape problems (missing required fields, unknown upload_id, invalid scheduled_for) return 400 and create no posts.

Per-target operational problems (the connection's token expired, the upstream platform rejected the post, the upload isn't ready yet) do not fail the whole request. You'll get 201 back with one post object per target; failed targets carry status: "failed" and a populated error object. Always iterate data and check each post's status instead of relying solely on the HTTP code.