Schedule and publish

Create scheduled posts, publish immediately, and post X/Twitter threads through the DunSocial API, using bearer auth and your workspace id header.

Post routes need Bearer auth and X-Workspace-Id.

Schedule a post

POST /api/posts/schedule

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": []
}'

Returns 201 with one post per social account. Validation is all-or-nothing: a character-limit or platform-metadata error creates zero posts. After validation passes, each account is inserted and queued. If QStash fails mid-batch, earlier accounts in that groupId may already be scheduled.

Validate without writing

POST /api/posts/validate

Same body as schedule / publish-now, without scheduledAt. Runs the same media, character-limit, per-platform metadata, and X monthly-cap checks. Does not create posts or queue jobs.

curl -X POST https://api.dunsocial.com/api/posts/validate \
-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.",
  "mediaUrls": []
}'

Returns 200:

{
"success": true,
"data": {
  "valid": false,
  "issues": [
    {
      "socialAccountId": "ACCOUNT_ID",
      "platform": "X",
      "code": "content_length",
      "message": "Content exceeds X character limit: 283/280 characters"
    }
  ]
}
}

valid: true and an empty issues array means the same payload can be sent to schedule or publish-now.

Publish now

POST /api/posts/publish-now

Same body as schedule, without scheduledAt. Optional naturalPosting boolean.

Threads (X only)

Body shape:

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

Threads need 2–25 tweets. Response includes threadHeadPost, totalTweets, and postIds.

Required per-platform metadata

When socialAccountIds includes that platform, the matching metadata block is required. There is no default Instagram format (do not assume reel).

X, LinkedIn, Bluesky, Threads, YouTube, and Facebook Pages do not need a metadata block for a text/media post. Facebook Pages are text, one link, and photos only (no video).

Character limits (on content)

Media on a post

mediaUrls can be media asset ids, https://media.dunsocial.com/... URLs, or storage keys like media/uploads/.... Stored and returned posts keep asset ids in mediaUrls.

Common errors

Check cap usage: GET /api/posts/x-cap-usage. Dry-run the same checks with POST /api/posts/validate.