Skip to content
Relay Port

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 /queues and post to it with mode: "queue".
  • GET /queues/{id}/preview forecasts the next free slots. It is a forecast, not a reservation: another post may take a slot first.
  • Set active: false with PATCH /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}/reshuffle moves the posts already queued onto the earliest free slots, in order.
  • Deleting a queue is refused with 409 Conflict while 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 set mode to schedule or queue. Each change raises the post's revision. Once a target has started publishing, the answer is 409 PostStateConflict: an edit never re-sends a target that may already have been sent.
  • POST /posts/{id}/publish publishes a draft or scheduled post now.
  • DELETE /posts/{id} cancels a post until a target starts publishing. The post stays readable with the status cancelled.