Skip to content

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.

Request body fields
FieldTypeRequiredDescription
contentstringYesThe text body of your post
platformsarrayYesPlatform targets (see Create Post)
scheduledForstringYesISO 8601 datetime to publish
timezonestringNoIANA timezone (default: "UTC")
mediaItemsarrayNoMedia attachments

Exact source field map; timezone defaults to UTC when omitted.

Credits failure matrix
CheckWhenOutcome if it fails
Credit check at schedulingWhen the scheduled post is createdCredits are checked at scheduling time
Credit check at publish timeAt the scheduled publish timePost 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.

Example scheduled post request
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"
  }'
Example scheduled post response
{
	"success": true,
	"status": "scheduled",
	"postId": "post_xyz789",
	"scheduledFor": "2026-03-29T13:00:00.000Z",
	"platforms": [{ "platform": "twitter", "success": true }]
}
Contract example 1
POST {{API_BASE_URL}}/v1/posts