Edit Scheduled Post API
Use the Edit Scheduled Post API to update a scheduled post before it publishes. You can change the content, replace mediaItems, change the platforms and their platformSpecificData, and optionally move the scheduled time in one call, provided the post is still in scheduled state and has not yet published or started publishing.
What this operation changes and when it is allowed
This operation changes what a scheduled post will publish. Its payload mirrors the create-post payload, except that publishNow is not part of this call. Because the editable values are overwritten as a set, include the complete intended configuration in every request instead of sending only the items that changed. Include every platform and media item you want the scheduled post to retain. Each platform is re-validated, and the credit difference is reconciled: adding a platform charges the extra credits, while removing one refunds them. Before calling, confirm the postId still refers to a post that is still scheduled. If it has already published or is already publishing, the update is not allowed and the request returns a conflict response. To find posts awaiting publication, use the list scheduled posts operation. If you only need to move the time, the reschedule operation is the narrower alternative.
Endpoint and path parameters
Send a PUT request to the endpoint shown in the endpoint table below, replacing postId in the path with the scheduled post ID. The postId path parameter is a string identifying the scheduled post. Authentication and content type follow the headers shown in the worked example: an x-access-key header and Content-Type: application/json.
Request body and full-replacement contract
The content field is required and carries the new post text body. The platforms field is required and carries the replacement target accounts, using the same shape as create, including platformSpecificData where a platform needs it. The mediaItems field is optional and carries replacement media attachments; omit it to clear media. The scheduledFor field is optional and carries a new ISO 8601 datetime; omit it to keep the current time. The timezone field is optional and carries an IANA timezone; omit it to keep the current one. Treat omission carefully: omitting mediaItems clears media, while omitting scheduledFor or timezone keeps the existing values. Always send content and the complete platforms list, even when only one platform or the text is changing.
Worked example and response
The worked example below updates the caption, replaces the media with a single image, targets Twitter and LinkedIn accounts, and moves the scheduled time to 2026-09-15T09:00:00Z in UTC. A successful response returns success as true, the message Scheduled post updated, the postId, and the scheduledFor value. Check the response postId and scheduledFor against what you sent before treating the edit as complete, and keep the returned scheduledFor for any follow-up scheduling logic.
Status codes and failure checks
Handle each status code as a distinct outcome rather than retrying blindly. A 200 response means the scheduled post was successfully updated. A 400 response means the payload was invalid or a platform rejected the content, so correct the payload and re-validate the platform targets before retrying. A 402 response means there are not enough credits for the added platforms, so reduce the added platforms or address the credit balance before retrying. A 403 response means a target platform is not available on your plan, so remove or replace that platform target. A 404 response means the post was not found, so verify the postId. A 409 response means the post already published or is not in scheduled state, so stop editing it as a scheduled post. A 503 response means scheduling is unavailable, so retry later rather than changing the payload.
| Method | Endpoint |
|---|---|
| PUT | {{API_BASE_URL}}/v1/posts/scheduled/{postId} |
Origin-modular parity contract; {{API_BASE_URL}} replaces the origin only.
| Parameter | Type | Description |
|---|---|---|
| postId | string | The scheduled post ID |
Exact source contract.
| Field | Type | Required | Description |
|---|---|---|---|
| content | string | Yes | New post text body |
| platforms | array | Yes | Replacement target accounts (same shape as create, incl. platformSpecificData) |
| mediaItems | array | No | Replacement media attachments. Omit to clear media |
| scheduledFor | string | No | New ISO 8601 datetime. Omit to keep the current time |
| timezone | string | No | IANA timezone. Omit to keep the current one |
Exact source contract, including omit semantics.
| Code | Meaning | Client action |
|---|---|---|
| 200 | Successfully updated | Confirm postId and scheduledFor in the response. |
| 400 | Invalid payload or a platform rejected the content | Correct the payload and re-validate platform targets before retrying. |
| 402 | Not enough credits for the added platforms | Reduce added platforms or address the credit balance before retrying. |
| 403 | A target platform is not available on your plan | Remove or replace the unavailable platform target. |
| 404 | Post not found | Verify the postId. |
| 409 | Post already published or not in scheduled state | Stop editing it as a scheduled post. |
| 503 | Scheduling unavailable | Retry later without changing the payload. |
Exact source meanings; client actions are operational guidance only.
curl -X PUT "{{API_BASE_URL}}/v1/posts/scheduled/post_xyz789" \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"mediaItems": [
{ "type": "image", "url": "https://cdn.example.com/new-photo.jpg" }
],
"platforms": [
{ "platform": "twitter", "accountId": "tw_123" },
{ "platform": "linkedin", "accountId": "li_456" }
],
"scheduledFor": "2026-09-15T09:00:00Z",
"timezone": "UTC"
}'{
"success": true,
"message": "Scheduled post updated",
"postId": "post_xyz789",
"scheduledFor": "2026-09-15T09:00:00.000Z"
}PUT {{API_BASE_URL}}/v1/posts/scheduled/{postId}