Skip to main content
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
RuleDetail
TimezoneStored and compared in UTC
Future onlyMust be in the future at submission time
WorkerCelery 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 paramValues
platformFilter by platform slug
platform_user_idFilter by account (Page ID, org ID, etc.)
statusscheduled, published, failed, cancelled, publishing
limit1–100
offsetPagination 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

ActionMethodEndpoint
ListGET/unified/scheduled-posts
Update timePATCH/unified/scheduled-posts/{id}
DeleteDELETE/unified/scheduled-posts/{id}
Publish nowPOST/unified/scheduled-posts/{id}/publish-now
Move to draftPOST/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

  1. Request hits platform video endpoint with future scheduled_time
  2. Post saved to scheduled_posts table (not published immediately)
  3. Celery task enqueued with countdown = scheduled_time - now
  4. 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