Posts

Create a post

Creates a draft, scheduled post, immediate post, or queued post. This endpoint requires a read-write API key. Provide exactly one creation mode: publishNow, scheduledFor, isDraft, or queuedFromProfile (optionally with queueId), which claims the next free slot in that profile's queue and returns it as scheduledFor. The accounts in platforms can belong to different profiles; an API key limited to selected profiles must have access to the profile of every account.

post/v1/posts

Request

  • Base URL: https://api.postzen.dev
  • URL: https://api.postzen.dev/v1/posts
  • Auth: HTTP bearer

Headers

x-request-idstring

Optional idempotency key. Repeating a value that already created a post returns 200 with the original post under existingPost (not post) and the message Post already exists for this request id, instead of creating a new one.

Request body

titlestring

Internal post title. YouTube uses this as the fallback video title when settings.title is omitted.

contentstring

Shared post text. Platform-specific validation still applies.

scheduledForstring date-time

ISO 8601 date for scheduled posts. Must be at least 60 seconds in the future.

publishNowboolean

Publish synchronously where possible.

isDraftboolean

Create a draft. platforms is optional for drafts.

queuedFromProfilestring

Profile id whose queue places the post. It can be any profile the API key can access and does not have to hold the target accounts; it is required when the accounts span more than one profile. PostZen assigns the next free slot and returns it as scheduledFor. Do not call GET /v1/queue/next-slot and pass the result as scheduledFor: the slot is only claimed by the create call itself, so a fetched slot can be taken by another request before yours arrives, and the post would be scheduled outside the queue.

queueIdstring

Specific queue on queuedFromProfile. Defaults to that profile's default queue. Requires queuedFromProfile.

timezonestring

Ignored in queue mode; queued posts take the queue's timezone.

tagsstring[]

Response

Idempotency replay: the x-request-id already created a post, so that post is returned under existingPost rather than post, and no new post is created.

message'Post already exists for this request id' required

Changes

No recorded changes to this operation across all 1 revision of this API.