Skip to content

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.

Endpoint
MethodEndpoint
PUT{{API_BASE_URL}}/v1/posts/scheduled/{postId}

Origin-modular parity contract; {{API_BASE_URL}} replaces the origin only.

Path parameters
ParameterTypeDescription
postIdstringThe scheduled post ID

Exact source contract.

Request body fields
FieldTypeRequiredDescription
contentstringYesNew post text body
platformsarrayYesReplacement target accounts (same shape as create, incl. platformSpecificData)
mediaItemsarrayNoReplacement media attachments. Omit to clear media
scheduledForstringNoNew ISO 8601 datetime. Omit to keep the current time
timezonestringNoIANA timezone. Omit to keep the current one

Exact source contract, including omit semantics.

Status codes and failure matrix
CodeMeaningClient action
200Successfully updatedConfirm postId and scheduledFor in the response.
400Invalid payload or a platform rejected the contentCorrect the payload and re-validate platform targets before retrying.
402Not enough credits for the added platformsReduce added platforms or address the credit balance before retrying.
403A target platform is not available on your planRemove or replace the unavailable platform target.
404Post not foundVerify the postId.
409Post already published or not in scheduled stateStop editing it as a scheduled post.
503Scheduling unavailableRetry later without changing the payload.

Exact source meanings; client actions are operational guidance only.

Edit a scheduled post with cURL
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"
  }'
Successful edit response
{
	"success": true,
	"message": "Scheduled post updated",
	"postId": "post_xyz789",
	"scheduledFor": "2026-09-15T09:00:00.000Z"
}
Contract example 1
PUT {{API_BASE_URL}}/v1/posts/scheduled/{postId}