Skip to content

Social Media Scheduling API

A social media scheduling API lets you schedule posts across multiple platforms from one integration.

Schedule a Post with curl
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"
  }'
Illustrative request
Example line 1

curl -X POST "{{API_BASE_URL}}/v1/posts" \

Illustrative request
Example line 2

-H "x-access-key: YOUR_API_KEY" \

Illustrative request
Example line 3

-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.

Scheduling Request Field Map
FieldType / shapeRequirednessPurpose
contentstringRequired in worked examplePost body text
platformsarray of { platform, accountId }Required in worked exampleTarget platforms and accounts
platformstringRequired per platforms entryPlatform identifier, e.g. twitter, linkedin
accountIdstringRequired per platforms entry in worked exampleConnected account identifier, e.g. abc123
scheduledForstring (date-time)Required for scheduled postsIntended local publish time
timezonestring (IANA timezone)Optional; defaults to UTC treatment of scheduledForIANA timezone, e.g. America/New_York
publishNowbooleanOptionalPublish immediately instead of scheduling
platformSpecificDataobjectOptionalNative platform settings such as YouTube premiere, TikTok privacy, Pinterest board targeting

Exact field names preserved from source contract; origin modularized as {{API_BASE_URL}}.

Scheduled Post Response Fields
FieldType / shapePurpose
successbooleanOverall request success
statusstringe.g. scheduled
postIdstringIdentifier of the created post, e.g. post_xyz789
scheduledForstring (UTC date-time)Scheduled time returned in UTC, e.g. 2026-03-29T13:00:00.000Z
platformsarray of { platform, success }Per-platform delivery result

Exact response shape preserved from source contract.

Scheduled Post Lifecycle Operations
Method and pathSemanticsKey parameters
GET /v1/posts/scheduledList posts waiting for publicationlimit, offset, sort (ascending or descending)
PUT /v1/posts/scheduled/{postId}Replace editable fields; send full desired statepostId; content, media, platforms, platformSpecificData, scheduled time
PATCH /v1/posts/scheduled/{postId}Change only the scheduled timepostId; new scheduledFor, optionally new timezone
DELETE /v1/posts/scheduled/{postId}Cancel scheduled post; moved back to draft, not deletedpostId

Exact methods and paths preserved from source contract.

Scheduling Failure Modes
Failure modeWhen it is detectedCheck to implement
Insufficient credits at publicationChecked at scheduling and again at publication timeMonitor credit balance for queued posts; surface insufficient credits error
Platform temporarily unavailableAt delivery timeInspect per-platform success; rely on built-in retry, then verify final status
Invalid or unvalidated mediaAt schedule timeValidate media when scheduling, not at delivery time
Missing timezoneAt scheduling timescheduledFor 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.

Scheduled Post Response
{
  "success": true,
  "status": "scheduled",
  "postId": "post_xyz789",
  "scheduledFor": "2026-03-29T13:00:00.000Z",
  "platforms": [
    {
      "platform": "twitter",
      "success": true
    }
  ]
}