Schedule Post API
The Schedule Post API lets you schedule a post for a specific date, time, and timezone. It uses the same create post endpoint with scheduledFor instead of publishNow, so you can queue content for later publication while keeping the same content, platform targets, and optional media attachments as an immediate post.
Endpoint: POST {{API_BASE_URL}}/v1/posts
Scheduling uses the same create post endpoint as immediate publishing, with one key difference in the request body. Instead of setting publishNow, you include scheduledFor with an ISO 8601 datetime for when the post should go live. Omit publishNow or set it to false so the request is treated as a scheduled post rather than an immediate one. The endpoint is POST {{API_BASE_URL}}/v1/posts, using the x-access-key header for authentication and a JSON body describing the content, platform targets, and schedule.
Request Body field map and input contract
The request body requires content as the text body of the post, platforms as the array of platform targets, and scheduledFor as an ISO 8601 datetime to publish. The timezone field is optional and accepts an IANA timezone string, defaulting to UTC when omitted. The mediaItems field is also optional and carries media attachments. Before sending, check that scheduledFor is present and formatted as an ISO 8601 datetime, that publishNow is omitted or false, and that each platform target is included in platforms. If any required field is missing, the scheduling request cannot be created as specified.
Example request
The example request in the Example scheduled post request section shows a post scheduled for 2026-03-29T09:00:00 in America/New_York, with content and a single twitter platform target using accountId abc123. The example response in the Example scheduled post response section shows success set to true, status set to scheduled, a postId, and the scheduledFor value converted to UTC. Use the returned postId to identify the scheduled post in later operations such as listing or deleting it.
Response contract
A successful scheduling response returns success as true and status as scheduled, along with postId and the scheduledFor time in UTC. The platforms array reports per-platform results, with each entry including platform and success. The scheduledFor value in the response shows the UTC time the post will be published, which is useful for verifying that the timezone conversion produced the intended instant. Compare the response scheduledFor against your intended local time to confirm the conversion before relying on the schedule.
Timezone Support
Pass any IANA timezone string, such as America/New_York, Europe/London, Asia/Jerusalem, Asia/Tokyo, or UTC. If no timezone is provided, scheduledFor is treated as UTC. This decision matters when you supply a local wall-clock time without a timezone: the system will interpret it as UTC rather than guessing your local zone. Always supply timezone explicitly when scheduledFor is expressed in a local time, and verify the UTC scheduledFor in the response matches the intended publish instant.
Credits
Balance is evaluated twice in this flow: once when the queued item is created, and once when its publish moment arrives. A shortfall that develops during the interval between those two moments leads to failure at the later point, reported as an insufficient credits error. For items queued well ahead, review the balance shortly before the intended publish moment as well as at creation, since passing the first evaluation does not guarantee passing the second.
| Field | Type | Required | Description |
|---|---|---|---|
| content | string | Yes | The text body of your post |
| platforms | array | Yes | Platform targets (see Create Post) |
| scheduledFor | string | Yes | ISO 8601 datetime to publish |
| timezone | string | No | IANA timezone (default: "UTC") |
| mediaItems | array | No | Media attachments |
Exact source field map; timezone defaults to UTC when omitted.
| Check | When | Outcome if it fails |
|---|---|---|
| Credit check at scheduling | When the scheduled post is created | Credits are checked at scheduling time |
| Credit check at publish time | At the scheduled publish time | Post fails with an insufficient credits error if credits ran out between scheduling and publish |
Credits are checked at scheduling time and again at publish time; the source-specified failure is at publish time if credits ran out between scheduling and publish.
curl -X POST "{{API_BASE_URL}}/v1/posts" \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "twitter", "accountId": "abc123" }
],
"scheduledFor": "2026-03-29T09:00:00",
"timezone": "America/New_York"
}'{
"success": true,
"status": "scheduled",
"postId": "post_xyz789",
"scheduledFor": "2026-03-29T13:00:00.000Z",
"platforms": [{ "platform": "twitter", "success": true }]
}POST {{API_BASE_URL}}/v1/posts