Scheduling

Schedule posts for future publication by adding scheduled_time to any post endpoint, or use the dedicated schedule-only API.

scheduled_time format

Use ISO 8601 UTC:

2026-07-10T14:30:00Z
2026-07-10T14:30:00+00:00

Rule	Detail
Timezone	Stored and compared in UTC
Future only	Must be in the future at submission time
Worker	Celery worker publishes when `scheduled_time <= now_utc`

Ensure your server clock and database use UTC for scheduling. Past-due posts that never publish often indicate a timezone mismatch.

Schedule on post endpoints

Add scheduled_time to POST /unified/post/text, /image, /video, or /carousel:

curl -X POST "https://backend.postsiva.com/unified/post/text" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{
    "platforms": ["linkedin"],
    "default_text": "This goes live tomorrow at 2:30 PM UTC.",
    "scheduled_time": "2026-07-10T14:30:00Z"
  }'

Works with platform overrides, multi-platform posts, and media IDs.

Mixed draft + publish

Use draft_platforms to schedule some platforms and publish others immediately — see Drafts.

Schedule-only endpoint

POST /unified/scheduled-posts accepts the same body shape as post endpoints but scheduled_time is required. Does not accept draft or draft_platforms.

curl -X POST "https://backend.postsiva.com/unified/scheduled-posts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{
    "post_type": "image",
    "platforms": ["instagram"],
    "default_text": "Scheduled Instagram post.",
    "default_image_id": "media-uuid",
    "scheduled_time": "2026-07-15T09:00:00Z"
  }'

List scheduled posts (get_queued_posts)

REST equivalent of MCP get_queued_posts with type=scheduled:

curl "https://backend.postsiva.com/unified/scheduled-posts?status=scheduled&limit=20" \
  -H "X-API-Key: psk_live_YOUR_KEY"

Query param	Values
`platform`	Filter by platform slug
`platform_user_id`	Filter by account (Page ID, org ID, etc.)
`status`	`scheduled`, `published`, `failed`, `cancelled`, `publishing`
`limit`	1–100
`offset`	Pagination offset

Response includes scheduled_time, scheduled_time_local, and scheduled_time_formatted (workspace owner timezone).

MCP: get_queued_posts

get_queued_posts(type="scheduled", platform="linkedin", status="scheduled")

Set type=all to include drafts. See MCP Tool Catalog.

Manage scheduled posts

Action	Method	Endpoint
List	`GET`	`/unified/scheduled-posts`
Update time	`PATCH`	`/unified/scheduled-posts/{id}`
Delete	`DELETE`	`/unified/scheduled-posts/{id}`
Publish now	`POST`	`/unified/scheduled-posts/{id}/publish-now`
Move to draft	`POST`	`/unified/scheduled-posts/{id}/move-to-draft`

Plan requirements

Scheduling requires scheduling_enabled on your plan. Each scheduled post also consumes a scheduled post credit. Blocked requests return 403 with plan upgrade details — see Postsiva errors.

Video scheduling flow

Request hits platform video endpoint with future scheduled_time
Post saved to scheduled_posts table (not published immediately)
Celery task enqueued with countdown = scheduled_time - now
Worker publishes at due time and updates status

Example: multi-platform schedule

{
  "platforms": ["linkedin", "threads", "facebook"],
  "default_text": "Coordinated launch.",
  "default_image_id": "media-uuid",
  "scheduled_time": "2026-08-01T16:00:00Z",
  "facebook": {
    "facebook_page_ids": ["756356074224043"]
  },
  "linkedin": {
    "linkedin_page_ids": ["108813535"],
    "post_to_personal": true
  }
}

Drafts

Save without scheduling

Platforms

Per-platform requirements

Get started

Features

REST API

MCP

Platforms

Guides

Integrations

Errors

Reference

scheduled_time format

Schedule on post endpoints

Mixed draft + publish

Schedule-only endpoint

List scheduled posts (get_queued_posts)

MCP: get_queued_posts

Manage scheduled posts

Plan requirements

Video scheduling flow

Example: multi-platform schedule

Drafts

Platforms

​scheduled_time format

​Schedule on post endpoints

​Mixed draft + publish

​Schedule-only endpoint

​List scheduled posts (get_queued_posts)

​MCP: get_queued_posts

​Manage scheduled posts

​Plan requirements

​Video scheduling flow

​Example: multi-platform schedule

​Related

Drafts

Platforms

scheduled_time format

Schedule on post endpoints

Mixed draft + publish

Schedule-only endpoint

List scheduled posts (get_queued_posts)

MCP: get_queued_posts

Manage scheduled posts

Plan requirements

Video scheduling flow

Example: multi-platform schedule

Related