API reference
Replace a draft or scheduled post, and keep it as a draft, schedule it or publish it now.
https://api.betterpost.dev/v1/posts/{id}A full replace: send the complete post. The body is the create body without
idempotencyKey, with exactly one of publishNow: true, scheduledFor or saveAsDraft: true. Credits are
reconciled per target (see Edit a post).
| Name | Description |
|---|---|
id | The post id. The post must be draft or scheduled. |
| Field | Type | Required | Description |
|---|---|---|---|
content | string | Yes | Shared text. |
platforms | array | Yes | Targets, as in create. |
mediaItems | array | No | Shared media. Default []. |
publishNow / scheduledFor / saveAsDraft | One mode | What to do with the post. | |
timezone | string | No | IANA time zone for scheduledFor. Default UTC. |
Schedule a draft:
curl -s -X PUT https://api.betterpost.dev/v1/posts/post_8f3k2m9q1x7v4n6b0c5d2a1z \
-H "x-access-key: $BETTERPOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Later",
"platforms": [
{ "platform": "twitter", "accountId": "acc_2x9c4v7b1n8m3k5j0h6g2f4d" },
{ "platform": "linkedin", "accountId": "acc_5l1n7k3j9h2g8f4d6s0a1q3w" }
],
"scheduledFor": "2026-11-01T09:00:00Z"
}'202 Accepted (or 200 OK when the result is a draft)
{
"success": true,
"status": "scheduled",
"postId": "post_8f3k2m9q1x7v4n6b0c5d2a1z",
"scheduledFor": "2026-11-01T09:00:00.000Z",
"platforms": [
{ "platform": "twitter", "accountId": "acc_2x9c4v7b1n8m3k5j0h6g2f4d", "success": true },
{ "platform": "linkedin", "accountId": "acc_5l1n7k3j9h2g8f4d6s0a1q3w", "success": true }
]
}The shape is the same as create.
| Status | Code | When |
|---|---|---|
200 | The post is (still) a draft. A previously scheduled post is refunded. | |
202 | The post was scheduled or published. | |
400 | validation_error, invalid_publish_mode, scheduled_in_past, ... | Same validation as create. |
401 | unauthorized | Missing or unknown API key. |
402 | insufficient_credits | The edit needs more credits than remain. Nothing changed. |
404 | not_found | No such post in this project. |
409 | not_editable | The post is not a draft or scheduled, or some targets already published. |
429 | rate_limited | More than 120 requests per minute. |