# How to schedule a post with the DunSocial API

> POST to /api/posts/schedule with socialAccountIds, content & an ISO scheduledAt, plus the bearer & workspace headers. You get one post per account back with 201. Validation is all-or-nothing, so one bad account creates no posts.

Updated: 2026-10-05.

## The request

Scheduling needs a bearer token, the workspace header & a JSON body:

```bash
curl -X POST https://api.dunsocial.com/api/posts/schedule \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "socialAccountIds": ["ACCOUNT_ID"],
    "content": "Shipping something small today.",
    "scheduledAt": "2026-08-01T15:00:00.000Z",
    "mediaUrls": []
  }'
```

The token needs the `posts:schedule` scope. Get account ids from the accounts routes, & use ids rather than handles.

## What comes back

A successful call returns 201 with one post per social account. Each post has its own id & status, so you can track them separately.

If you target three accounts, you get three posts that share a group.

## Validation is all-or-nothing

Before anything is created, DunSocial validates the whole request. A character-limit or missing platform-option error creates zero posts.

After validation passes, each account is inserted & queued. If the queue fails partway through a batch, earlier accounts in that group may already be scheduled, so check the response rather than assuming.

## Publish now

For an immediate post, call the publish route with the same body, minus `scheduledAt`:

```bash
curl -X POST https://api.dunsocial.com/api/posts/publish-now \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"socialAccountIds":["ACCOUNT_ID"],"content":"Live now."}'
```

It needs `posts:publish`. An optional `naturalPosting` boolean is available.

DunSocial queues the post immediately, so the response tells you it was accepted, not that the platform has finished.

## X threads

Threads have their own routes, `/api/posts/schedule-thread` & `/api/posts/publish-thread-now`, & take a single `socialAccountId` & a `tweets` array of 2 to 25 items:

```json
{
  "socialAccountId": "ACCOUNT_ID",
  "scheduledAt": "2026-08-01T15:00:00.000Z",
  "tweets": [
    { "content": "First tweet", "mediaUrls": [] },
    { "content": "Second tweet" }
  ]
}
```

The response includes the thread head, the total tweet count & the post ids.

DunSocial shows a thread on the same calendar as your other scheduled posts, so you can review it there.

## Media on a post

`mediaUrls` can be media asset ids, `https://media.dunsocial.com/...` URLs or storage keys. Stored & returned posts keep asset ids.

DunSocial shows API-created posts on the same calendar as any other, so a person can review one before it goes out.

## Common errors

A 400 means a character limit, missing platform option or bad media. A 404 means a media asset is missing. A 429 means the X monthly cap was reached.

Call the validate route first to catch the 400s without creating anything. DunSocial's error text usually names the field or rule that failed.

## Related guides

- [How to validate a social post before scheduling it with the API](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-validate-a-social-post-before-scheduling-it-with-the-api.md)
- [How to authenticate with the DunSocial API](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-authenticate-with-the-dunsocial-api.md)
- [What platform options does the DunSocial API require?](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/what-platform-options-does-the-dunsocial-api-require.md)
- [How to schedule social media posts from the command line](https://www.dunsocial.com/hub/social-media-automation-for-developers/how-to-schedule-social-media-posts-from-the-command-line.md)

## About this document

This is the Markdown representation of https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-schedule-a-post-with-the-dunsocial-api. The HTML version of the same page is at the same URL. You can also request Markdown from any page by sending `Accept: text/markdown`.

Machine-readable summary of the whole site: https://www.dunsocial.com/llms.txt

## Company

- Product: DunSocial, https://www.dunsocial.com
- Legal entity: THISUX PRIVATE LIMITED, Chennai, Tamil Nadu, India
- Support: support@dunsocial.com
- Open the app: https://app.dunsocial.com/login