Reschedule Post API
The Reschedule Post API moves an existing scheduled post to a new time without recreating the post. You identify the scheduled post with the required postId path parameter, send the new time as scheduledFor, and optionally supply timezone when an IANA timezone is needed to interpret that time. The request uses PATCH /v1/posts/scheduled/{postId} and requires the x-access-key header.
Reschedule Post API operation summary with exact PATCH endpoint
Use this operation when a scheduled post already exists and only its delivery time needs to change. The endpoint is PATCH /v1/posts/scheduled/{postId}. Replace the postId segment with the identifier of the scheduled post you want to move, and send a JSON body containing the new schedule time. The worked request example below shows the source example value for scheduledFor and uses the modular base URL placeholder before the unchanged path.
Authorization: x-access-key header
Every call requires the x-access-key header, with the token supplied as the header value. Send Content-Type: application/json with the request body. Before sending, confirm that the token is present, that postId is the scheduled post identifier rather than a draft or published post identifier, and that scheduledFor is formatted as an ISO 8601 datetime. If the header is missing or the identifier is wrong, do not treat a non-200 response as a successful reschedule; check the status and message fields described below.
Path Parameters: postId
The postId path parameter is a required string and identifies the scheduled post to reschedule. It belongs in the path, not in the JSON body. Keep the path segment exactly as /v1/posts/scheduled/{postId} and substitute only the identifier value. A mismatch here is the most likely reason a request targets the wrong scheduled post, so verify the identifier against the scheduled post you intend to move before sending the PATCH request.
Request Body: scheduledFor and timezone field map
The request body is a JSON object with two fields. scheduledFor is required, is a string, and must be an ISO 8601 datetime representing the new time to schedule the post. timezone is optional, is a string, and holds an IANA timezone when you need to specify the timezone for interpreting the new time. The field map table below separates required and optional fields by location, type, and format so implementers can validate inputs before making the call. The request example shows a body containing only the required scheduledFor field.
Response Body overview
Responses use application/json. A 200 response confirms the reschedule and includes success, message, and scheduledFor, where scheduledFor echoes the new schedule time in the response contract. The 404, 409, and 503 responses include only success and message. The status-code decision table below records only those documented shapes; it does not assign causes to the error statuses because the source contract does not describe them. Always branch on the HTTP status first, then read success and message, and only read scheduledFor from a 200 response.
200 response: success, message, scheduledFor
For a 200 application/json response, expect success as a boolean, message as a string, and scheduledFor as a string. Treat scheduledFor in this response as the authoritative new time returned for the rescheduled scheduled post, and compare it with the scheduledFor value you sent. The 200 response example below shows the exact documented shape with placeholder string values.
404 response: success and message only
A 404 application/json response contains success and message only, with no scheduledFor field in the documented shape. Do not read a new schedule time from this response. Record the status and message, verify that postId refers to the intended scheduled post, and stop rather than assuming the post was moved.
409 response: success and message only
A 409 application/json response also contains success and message only, with no scheduledFor field in the documented shape. Do not read a new schedule time from this response. Record the status and message and do not retry blindly; the documented contract does not specify a cause or a retry rule for this status.
503 response: success and message only
A 503 application/json response contains success and message only, with no scheduledFor field in the documented shape. Do not read a new schedule time from this response. Record the status and message and treat the reschedule as not confirmed by this response.
Implementation checklist and unresolved source gaps
Before implementing or calling this endpoint, run through a short checklist. Confirm the method is PATCH and the path is /v1/posts/scheduled/{postId}. Confirm the x-access-key header is present. Confirm postId is a required string in the path. Confirm scheduledFor is present, is a string, and uses an ISO 8601 datetime format. Confirm timezone, when present, is a string containing an IANA timezone. After the call, confirm the status is 200 application/json before reading scheduledFor, and handle 404, 409, and 503 by reading success and message only. If you need to find the scheduled post identifier first, the adjacent list operation for scheduled posts is the natural preceding step.
| Field | Location | Required | Type | Format / notes |
|---|---|---|---|---|
| x-access-key | Header | Required | string | Token supplied as header value |
| postId | Path | Required | string | Identifies the scheduled post |
| scheduledFor | Request body | Required | string | ISO 8601 datetime; new time to schedule the post |
| timezone | Request body | Optional | string | IANA timezone |
| success | Response body | Required | boolean | Present in documented 200, 404, 409 and 503 shapes |
| message | Response body | Required | string | Present in documented 200, 404, 409 and 503 shapes |
| scheduledFor | Response body | Required in 200 shape | string | Present in 200 application/json response |
Exact source contract; origin modularized as {{API_BASE_URL}}.
| Status | Content type | Documented response fields | How to handle |
|---|---|---|---|
| 200 | application/json | success, message, scheduledFor | Read scheduledFor as the returned new schedule time |
| 404 | application/json | success, message | Do not read scheduledFor; verify postId |
| 409 | application/json | success, message | Do not read scheduledFor; record status and message |
| 503 | application/json | success, message | Do not read scheduledFor; treat reschedule as not confirmed |
Only documented shapes are stated; causes for 404, 409 and 503 are not described in the source contract.
curl -X PATCH "{{API_BASE_URL}}/v1/posts/scheduled/string" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"scheduledFor": "2019-08-24T14:15:22Z"
}'{
"success": true,
"message": "string",
"scheduledFor": "string"
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| postId#1 | postId | string | __0 | Yes | ||
| body#2 | body | object | __0 | Yes | ||
| body#2 | body.scheduledFor | string | __1 | Yes | New ISO 8601 datetime to schedule the post | kind: schemaFormat; value: date-time |
| body#2 | body.timezone | string | __2 | No | IANA timezone | |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes | ||
| response#3 | response.scheduledFor | string | __3 | Yes | ||
| response#4 | response | object | __0 | |||
| response#4 | response.success | boolean | __1 | Yes | ||
| response#4 | response.message | string | __2 | Yes |