Publishing
Scheduling
The four post modes, times and time zones, queues with weekly slots, stagger, and how editing and cancelling work.
Four modes, always explicit
Every POST /posts names its mode, so a post is never scheduled or published by accident because a field was missing:
mode |
What happens |
|---|---|
draft |
The post is saved and nothing is scheduled. Platform rules are checked when you schedule or publish it. |
schedule |
The post goes out at scheduledAt, or at the scheduledAt each target carries. |
publish_now |
Publishing starts at once and the answer is 202 Accepted. The key also needs posts:publish. |
queue |
The post takes the earliest free slot of a queue: queueId, or default for the workspace's default queue. The chosen time comes back in scheduledAt. |
A post has 1 to 20 targets, one per connected account, all in one brand. A target can override the post's text, title, media, scheduledAt and platformData; a target's platformData is flat and wins over the post's, which is keyed by platform.
Times
Send times in RFC 3339 with an offset or Z, such as 2026-12-01T09:00:00+09:00. Responses are in UTC. Each target's dueAt is the moment it is due, and leadMs is how long before that moment Relay Port starts preparing its media.
Queues
A queue is a weekly list of posting times in one time zone, such as weekdays at 09:00 and 18:00 in Asia/Tokyo. Slots are kept as local times, so they stay at the same local hour when daylight saving time changes.
- Create one with
POST /queuesand post to it withmode: "queue". GET /queues/{id}/previewforecasts the next free slots. It is a forecast, not a reservation: another post may take a slot first.- Set
active: falsewithPATCH /queues/{id}to pause a queue. Queued posts keep their times and new posts cannot take its slots. - After you edit the slots,
POST /queues/{id}/reshufflemoves the posts already queued onto the earliest free slots, in order. - Deleting a queue is refused with
409 Conflictwhile posts are scheduled in it.
Stagger
stagger: { "minSeconds": 60, "maxSeconds": 900 } spreads the targets that have no time of their own across random gaps. The gaps are picked when the post is created and stored in each target's dueAt, so the times you read back are the times that will be used.
Editing, publishing and cancelling
PATCH /posts/{id}changes a draft or scheduled post, and a draft becomes scheduled when you setmodetoscheduleorqueue. Each change raises the post'srevision. Once a target has started publishing, the answer is409 PostStateConflict: an edit never re-sends a target that may already have been sent.POST /posts/{id}/publishpublishes a draft or scheduled post now.DELETE /posts/{id}cancels a post until a target starts publishing. The post stays readable with the statuscancelled.