Scheduled posts

/api/v1/scheduled-posts is two endpoints. GET lists the user's queue. POST inserts a new row that will fire when its scheduled_for elapses. The same cron worker that drains the in-app composer's queue picks up rows written through this endpoint, so an integration can offload "schedule for later" to Post-EZ without re-implementing the publish dispatcher.

List queue

curl -X GET 'https://postez.app/api/v1/scheduled-posts?limit=20&status=scheduled' \
  -H "Authorization: Bearer pz_YOUR_KEY_HERE"

Required scope: scheduled.read. Rate limit: 600 requests per minute per key.

Query parameters

• limit (number, optional) — max rows to return. Default 50, max 200.
• status (string, optional) — comma-separated list of statuses to filter on, e.g. scheduled,publishing,failed.

Response

{
  "ok": true,
  "posts": [
    {
      "id": "9d4a...",
      "caption": "Launch announcement",
      "media_urls": ["https://..."],
      "platforms": ["instagram", "x"],
      "scheduled_for": "2026-06-01T15:00:00.000Z",
      "status": "scheduled",
      "fail_reason": null,
      "retry_count": 0,
      "created_at": "2026-05-22T18:01:09.000Z",
      "updated_at": "2026-05-22T18:01:09.000Z"
    }
  ]
}

Status enum

• scheduled — waiting for scheduled_for to elapse.
• publishing — claimed by the cron worker, mid-dispatch.
• published — terminal success.
• failed — terminal failure (check fail_reason).

Create a scheduled post

curl -X POST https://postez.app/api/v1/scheduled-posts \
  -H "Authorization: Bearer pz_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": ["instagram", "x"],
    "content": "Hello from the future.",
    "scheduled_for": "2026-06-01T15:00:00Z"
  }'

Required scope: scheduled.write. Rate limit: 60 requests per minute per key.

Body fields

• platforms (string[], required) — same enum as /publish.
• content (string, required) — caption. Combined with title (if provided) as title\n\ncontent.
• title (string, optional) — newsletter / video title.
• scheduled_for (string, required) — ISO 8601 timestamp with timezone, e.g. 2026-06-01T15:00:00Z or 2026-06-01T11:00:00-04:00. Must be at least 60 seconds in the future so the cron worker has time to claim the row before it elapses.
• media_urls (string[], optional) — publicly-reachable URLs. Same rules as /publish.

Response

201 Created with the inserted row. The id is what you'd reference in a future "cancel scheduled post" call.

{ "ok": true, "post": { "id": "9d4a...", "status": "scheduled", ... } }

Validation codes: missing_content, missing_platforms, missing_schedule, invalid_schedule, schedule_in_past.