Reschedule Post API
The Reschedule Post API changes the scheduled time of an existing scheduled post without recreating it. You identify the post with postId, supply a new ISO 8601 datetime in scheduledFor, and optionally supply an IANA timezone so the local time is interpreted correctly. A successful call returns the message Post rescheduled. and the new scheduledFor value in UTC.
Endpoint
Use PATCH {{API_BASE_URL}}/v1/posts/scheduled/{postId} to change the scheduled time of an existing scheduled post. The method and path are the contract for this operation: the postId is part of the path, and the new time is supplied in the request body. Keep the path unchanged when configuring the base URL, and replace only the origin with your configured API base URL.
Path Parameters
The path contains one parameter, postId, typed as a string and described as the post ID to reschedule. Before calling, confirm that the identifier belongs to a post that is still scheduled. If the identifier does not match a post, the documented result is Post not found. If the post has already moved out of the scheduled state, the documented result is a conflict rather than a successful reschedule.
Request Body
The request body has two fields. scheduledFor is a required string containing a new ISO 8601 datetime. timezone is an optional string containing an IANA timezone. Supply timezone when scheduledFor is expressed as a local wall-clock time in a named zone, so the intended instant is unambiguous. The input contract table below lists each field with its type, requiredness, and description for direct implementation matching.
Example
The cURL example in the Reschedule Post API cURL Example shows the full request: the PATCH method, the unchanged scheduled-post path with a sample postId, the x-access-key header using a placeholder key, and a JSON body with scheduledFor and timezone. Replace the sample postId and placeholder key with your own values before use. The example is illustrative and has not been executed as part of this draft.
Response
On success, the response contains success set to true, the message Post rescheduled., and scheduledFor set to the new time in UTC. In the worked example, a request for 2026-03-30T14:00:00 in Asia/Jerusalem returns 2026-03-30T11:00:00.000Z, a three-hour shift that reflects the conversion from that local zone to UTC. Always read the returned scheduledFor value rather than assuming the request string is echoed back unchanged, because the response normalizes the time to UTC.
Status Codes
Handle each documented status code explicitly. A 200 response means the post was successfully rescheduled. A 404 response means Post not found, so verify the postId and that the post still exists. A 409 response means the post is already published or not in scheduled state, so do not retry the same reschedule as if it were still scheduled; fetch the current state first. A 503 response means Scheduling unavailable, so treat the attempt as not completed and retry later or surface the failure. The failure matrix below maps each code to its meaning and the caller action it implies.
| Parameter | Type | Description |
|---|---|---|
| postId | string | The post ID to reschedule |
Exact source contract: postId is a string path parameter.
| Field | Type | Required | Description |
|---|---|---|---|
| scheduledFor | string | Yes | New ISO 8601 datetime |
| timezone | string | No | IANA timezone |
Exact source contract: scheduledFor required, timezone optional.
| Code | Meaning | Caller Action |
|---|---|---|
| 200 | Successfully rescheduled | Read the returned scheduledFor value in UTC and confirm the new time. |
| 404 | Post not found | Verify postId and that the post exists before retrying. |
| 409 | Post already published or not in scheduled state | Fetch the current post state; do not reschedule as a scheduled post. |
| 503 | Scheduling unavailable | Treat as not completed; retry later or surface the failure. |
Exact source status meanings; caller action is explanatory guidance.
Frequently asked questions
What do I send to reschedule a post?
Send PATCH to {{API_BASE_URL}}/v1/posts/scheduled/{postId} with postId in the path and scheduledFor in the body. Add timezone as an IANA timezone when you want the supplied local time interpreted in that zone.
How does the timezone conversion work in the example?
The request uses an ISO 8601 datetime such as 2026-03-30T14:00:00. In the worked example, 14:00 in Asia/Jerusalem is returned as 2026-03-30T11:00:00.000Z, showing the three-hour conversion to UTC.
What should I do when rescheduling returns an error?
A 404 means Post not found, so check the postId. A 409 means the post is already published or not in scheduled state, so it cannot be rescheduled as a scheduled post. A 503 means Scheduling unavailable, so retry later or surface the failure to the caller.
curl -X PATCH "{{API_BASE_URL}}/v1/posts/scheduled/post_xyz789" \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scheduledFor": "2026-03-30T14:00:00",
"timezone": "Asia/Jerusalem"
}'{
"success": true,
"message": "Post rescheduled.",
"scheduledFor": "2026-03-30T11:00:00.000Z"
}PATCH {{API_BASE_URL}}/v1/posts/scheduled/{postId}