Posts and lifecycle

The five post statuses and the transitions between them.

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

id · string

Post id.

url · 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.

content · string

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

status · string

One of the five statuses above.

targetPlatforms · string[]

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

scheduledAt · string | null

ISO timestamp of the pending dispatch.

scheduledPlatform · string | null

The single platform a scheduled post will publish to.

externalPostId · string | null

Platform-side id, set once posted.

postedAt · string | null

When it went live.

failureReason · string | null

Platform and message from the last failed dispatch.

dispatchAttempts · number

Delivery attempts made by the scheduler.

assets · object[]

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

organizationId · string

The studio that owns the post.

authorId · string

User who created it.

createdAt · string

Creation timestamp.

updatedAt · 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.