Social Media Scheduling API
A social media scheduling API lets you schedule posts across multiple platforms from one integration.
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"
}'curl -X POST "{{API_BASE_URL}}/v1/posts" \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
Set the date, time, and timezone, and publishing is handled automatically at the scheduled moment. This guide covers the scheduling request, timezone-aware delivery, rich media scheduling, cross-platform scheduling, and how to manage scheduled posts before they publish.
What a social media scheduling API does
This kind of interface allows an application to hand over a post now and have it go out later, at a moment you choose. Rather than wiring a separate timer for every network, you link accounts a single time and then reuse one familiar request format. That design suits products where people want to prepare material early, aim releases at busy periods, or let generated copy flow out on a schedule without a custom publishing worker.
Add scheduling to your product in three steps
Setup has three stages. Obtain a key and place it in the x-access-key header for each call. Then connect through the REST endpoint, after which publishing, scheduling, analytics, comment handling and messaging all travel through the same interface. Finally, your users gain reach across the major networks without you maintaining a bespoke connector for each one. The example titled Schedule a Post with curl demonstrates the request, while Scheduled Post Response illustrates the reply you should parse.
Timezone handling and the UTC default
Getting local timing right is where many schedulers stumble. Supply scheduledFor alongside an IANA timezone such as America/New_York and the item goes out at the intended local moment, sparing you manual conversion to UTC. Identifiers like Europe/London, Asia/Jerusalem, Asia/Tokyo and UTC are equally acceptable. Leave timezone out and scheduledFor is read as UTC, so include the zone whenever local timing matters, then check the returned scheduledFor, which comes back in UTC.
Cross-platform and platform-specific scheduling
With cross-platform scheduling, a single call can address several networks together. List each destination inside platforms, pairing its platform name with the relevant accountId, and formatting is adapted per network. For network-specific behaviour, use platformSpecificData: examples include premiere options on YouTube, privacy choices on TikTok and board selection on Pinterest. Keeping those options apart from shared fields stops one network's setting from bleeding into another.
Rich media scheduling
Rich media scheduling covers material such as pictures, clips, multi-image sets, Reels, Shorts and Stories. A key advantage is timing of checks: assets are examined when you queue the item, rather than at the moment it is due. If an asset is faulty, you learn about it during scheduling and can repair it before the release moment arrives.
Delivery and retry
Queued items benefit from automatic retry behaviour. Should a network be briefly unreachable, delivery is attempted again on its own. Even so, you should verify outcomes yourself: look at each platform entry's success flag in the reply and confirm the final state per destination, since an overall successful request does not guarantee every network delivered.
Managing scheduled posts: list, edit, reschedule, cancel
While an item is still waiting, you can inspect, revise or withdraw it. GET /v1/posts/scheduled lists what is pending, with limit, offset and sort controlling paging and order. PUT /v1/posts/scheduled/{postId} overwrites the editable portion, so include the whole intended version covering text, attachments, destinations, network-specific options or timing. PATCH /v1/posts/scheduled/{postId} suits a timing-only change, taking a new scheduledFor and optionally a new timezone. DELETE /v1/posts/scheduled/{postId} withdraws a queued item before it goes out, sending it back to draft rather than erasing it. The table titled Scheduled Post Lifecycle Operations contrasts these behaviours.
Credit checks and failure modes
Balance is examined at two points: when an item enters the queue and when its release moment arrives. A shortfall at the later point means publication fails with an insufficient credits error. Because that second examination can catch people out, keep an eye on balances for accounts holding queued items and show the failure clearly instead of letting the item vanish quietly. The table titled Scheduling Failure Modes gathers the checks worth building.
Choosing a unified API versus per-platform integrations
A unified scheduler makes sense when consistent timing, timezone handling and queue management across many networks matter more than deep native control, and when maintaining separate connectors would be costly. Separate native integrations may suit you better if a network's special behaviour is central and not exposed through the unified layer. Judge either route against the features you truly need: cross-platform scheduling, timezone-aware delivery, rich media scheduling, platformSpecificData support, and the ability to list, edit, reschedule and cancel scheduled posts before publication.
| Field | Type / shape | Requiredness | Purpose |
|---|---|---|---|
| content | string | Required in worked example | Post body text |
| platforms | array of { platform, accountId } | Required in worked example | Target platforms and accounts |
| platform | string | Required per platforms entry | Platform identifier, e.g. twitter, linkedin |
| accountId | string | Required per platforms entry in worked example | Connected account identifier, e.g. abc123 |
| scheduledFor | string (date-time) | Required for scheduled posts | Intended local publish time |
| timezone | string (IANA timezone) | Optional; defaults to UTC treatment of scheduledFor | IANA timezone, e.g. America/New_York |
| publishNow | boolean | Optional | Publish immediately instead of scheduling |
| platformSpecificData | object | Optional | Native platform settings such as YouTube premiere, TikTok privacy, Pinterest board targeting |
Exact field names preserved from source contract; origin modularized as {{API_BASE_URL}}.
| Field | Type / shape | Purpose |
|---|---|---|
| success | boolean | Overall request success |
| status | string | e.g. scheduled |
| postId | string | Identifier of the created post, e.g. post_xyz789 |
| scheduledFor | string (UTC date-time) | Scheduled time returned in UTC, e.g. 2026-03-29T13:00:00.000Z |
| platforms | array of { platform, success } | Per-platform delivery result |
Exact response shape preserved from source contract.
| Method and path | Semantics | Key parameters |
|---|---|---|
| GET /v1/posts/scheduled | List posts waiting for publication | limit, offset, sort (ascending or descending) |
| PUT /v1/posts/scheduled/{postId} | Replace editable fields; send full desired state | postId; content, media, platforms, platformSpecificData, scheduled time |
| PATCH /v1/posts/scheduled/{postId} | Change only the scheduled time | postId; new scheduledFor, optionally new timezone |
| DELETE /v1/posts/scheduled/{postId} | Cancel scheduled post; moved back to draft, not deleted | postId |
Exact methods and paths preserved from source contract.
| Failure mode | When it is detected | Check to implement |
|---|---|---|
| Insufficient credits at publication | Checked at scheduling and again at publication time | Monitor credit balance for queued posts; surface insufficient credits error |
| Platform temporarily unavailable | At delivery time | Inspect per-platform success; rely on built-in retry, then verify final status |
| Invalid or unvalidated media | At schedule time | Validate media when scheduling, not at delivery time |
| Missing timezone | At scheduling time | scheduledFor treated as UTC; send IANA timezone explicitly when local time matters |
Failure semantics preserved from source; no reinterpretation of credit behavior.
Frequently asked questions
What is a social media scheduling API?
It is an interface that lets software queue a post for a later moment instead of sending it straight away. A planning dashboard might use it so people can prepare material ahead of time, and a content-generation system might use it to place generated material across several networks without manual intervention.
Which timezones are supported?
Any zone identifier in IANA form is accepted, for instance America/New_York, Europe/London, Asia/Jerusalem, Asia/Tokyo or UTC. Omitting the timezone means the scheduledFor value is interpreted as UTC.
Can I schedule posts to multiple social platforms?
Yes. Put every destination account into the platforms array within a single scheduling call. One shared request format covers the supported networks.
Can I see all of my upcoming scheduled posts?
Yes. Calling GET /v1/posts/scheduled returns queued items in pages. The limit parameter sets how many come back, offset moves you through the set, and sort chooses ascending or descending order.
Can I edit a scheduled post before it is published?
Yes, while it remains queued. PUT /v1/posts/scheduled/{postId} can revise text, attachments, destinations, network-specific options or timing. Because this operation overwrites the editable portion, include the complete intended version rather than a partial change.
Can I change only the scheduled time?
Yes. PATCH /v1/posts/scheduled/{postId} is designed for a timing-only adjustment. Supply a fresh scheduledFor, and add timezone if the zone also needs to change.
Can I cancel a scheduled post?
Yes, provided publication has not happened yet. DELETE /v1/posts/scheduled/{postId} removes it from the queue and returns it to draft status instead of erasing it.
What happens if I run out of credits before a scheduled post publishes?
Balance is examined twice: once when the item is queued and once when its moment arrives. A shortfall at the second examination causes publication to fail with an insufficient credits error.
{
"success": true,
"status": "scheduled",
"postId": "post_xyz789",
"scheduledFor": "2026-03-29T13:00:00.000Z",
"platforms": [
{
"platform": "twitter",
"success": true
}
]
}