Posts and lifecycle

A post is one piece of content plus the platforms it targets. It moves through five statuses:

Status	Meaning
`draft`	Being written. Fully editable.
`scheduled`	Has a future `scheduledAt` and a resolved `scheduledPlatform`.
`queued`	Claimed by the scheduler and handed to the dispatch queue.
`posted`	Live on the platform. `externalPostId` holds the platform’s id.
`failed`	Dispatch gave up. `failureReason` says why.

create_draft ──▶ draft ──schedule_post──▶ scheduled ──cron──▶ queued ──▶ posted
                   │                          │                  │
                   └──────publish_post────────┘                  └──▶ failed
                                                                       │
                              unschedule_post ◀─────────────────────────┘

What’s editable when

Action	Allowed from
Edit `content`	`draft`, `scheduled`
Edit `targetPlatforms`	`draft` only — unschedule first
`delete_draft`	Any status except `queued`
`publish_post`	`draft` only
`schedule_post`	`draft`, `scheduled` (re-schedule), `failed` (retry)
`unschedule_post`	`scheduled`, `failed` — returns it to `draft`

Editing the content of a scheduled post re-checks the length limit for the platform it is already aimed at, so an edit can’t silently break dispatch. Retargeting is draft-only because the resolved scheduledPlatform would go stale.

Fields

string

Post id.

string

Deep link into the web studio ({WEB_ORIGIN}/posts/{id}). Share this with the user instead of a bare id. Requires them to be signed in — it is not a public share link.

string

Body text, up to 10,000 characters at draft time.

string

One of the five statuses above.

string[]

Platforms this post may go to, e.g. ["linkedin"].

string | null

ISO timestamp of the pending dispatch.

string | null

The single platform a scheduled post will publish to.

string | null

Platform-side id, set once posted.

string | null

When it went live.

string | null

Platform and message from the last failed dispatch.

number

Delivery attempts made by the scheduler.

object[]

Attached assets — { id, postId, kind, mimeType, filename, bytes, status }.

string

The studio that owns the post.

string

User who created it.

string

Creation timestamp.

string

Last modification timestamp.

Targets vs. the publish target

targetPlatforms is a list of candidates. Publishing is always single-target:

One target → publish_post and schedule_post resolve it automatically.
Several targets → pass platform explicitly, or you get specify_platform.
A platform outside the list is rejected with post_does_not_target_<id>.

Creating a draft with no targetPlatforms (or an empty array) targets every supported platform.

Get started

Concepts

Guides

What’s editable when

Fields

Targets vs. the publish target

​What’s editable when

​Fields

​Targets vs. the publish target

What’s editable when

Fields

Targets vs. the publish target