> ## Documentation Index > Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt > Use this file to discover all available pages before exploring further. # Reschedule an appointment > Moves the appointment. Where the EHR implements a move as cancel-plus-create, the response returns BOTH ids and sets `implementedAsCancelAndCreate: true` — the previous EHR record is a tombstone rather than an updated appointment. Target capacity is reserved before contacting the EHR; an unavailable target returns 409. If the current duration is unknown, supply `durationMinutes` or refresh the appointment before moving it. Send an `Idempotency-Key` header to make a retry safe: it is honoured for 24 hours per app+organization, a repeat of the SAME request replays the original result, and a key reused for a DIFFERENT request is refused with 409. The guarantee fails closed — if the idempotency store is unreachable the request is refused with 503 `idempotency_unavailable` rather than proceeding unguarded. A lost vendor response returns 409 `ehr_write_uncertain` with `requiresReconciliation: true`. Both the original and target capacity remain reserved until the outcome is verified. ## OpenAPI ````yaml /openapi-v4.json patch /appointments/{id} openapi: 3.0.0 info: title: Max AI Public API description: API for third-party marketplace apps version: '4.0' contact: {} servers: - url: https://api.maxcare.ai/v4 security: [] tags: [] paths: /appointments/{id}: patch: tags: - Appointments summary: Reschedule an appointment description: >- Moves the appointment. Where the EHR implements a move as cancel-plus-create, the response returns BOTH ids and sets `implementedAsCancelAndCreate: true` — the previous EHR record is a tombstone rather than an updated appointment. Target capacity is reserved before contacting the EHR; an unavailable target returns 409. If the current duration is unknown, supply `durationMinutes` or refresh the appointment before moving it. Send an `Idempotency-Key` header to make a retry safe: it is honoured for 24 hours per app+organization, a repeat of the SAME request replays the original result, and a key reused for a DIFFERENT request is refused with 409. The guarantee fails closed — if the idempotency store is unreachable the request is refused with 503 `idempotency_unavailable` rather than proceeding unguarded. A lost vendor response returns 409 `ehr_write_uncertain` with `requiresReconciliation: true`. Both the original and target capacity remain reserved until the outcome is verified. operationId: AppointmentsPublicController_rescheduleAppointment parameters: - name: id required: true in: path description: Appointment ID schema: type: string - name: idempotency-key required: false in: header description: Client-generated key protecting retries for 24 hours schema: type: string - name: X-Organization-Id in: header required: true schema: type: string description: Target clinic organization ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RescheduleAppointmentBody' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/RescheduleAppointmentSuccessResponse' '400': description: Missing or invalid request parameter content: application/json: schema: $ref: '#/components/schemas/PublicApiBadRequestResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/PublicApiUnauthorizedResponse' '403': description: Insufficient scope content: application/json: schema: $ref: '#/components/schemas/PublicApiForbiddenResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/PublicApiNotFoundResponse' '409': description: Resource conflict (e.g. editing a signed note) content: application/json: schema: $ref: '#/components/schemas/PublicApiConflictResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/PublicApiRateLimitResponse' '502': description: EHR sync failed content: application/json: schema: $ref: '#/components/schemas/PublicApiBadGatewayResponse' '503': description: EHR integration unavailable content: application/json: schema: $ref: '#/components/schemas/PublicApiServiceUnavailableResponse' security: - api-key: [] components: schemas: RescheduleAppointmentBody: type: object properties: startsAt: type: string description: New start instant, ISO-8601 with offset example: '2026-08-05T10:30:00-04:00' durationMinutes: type: number description: New length in minutes example: 30 providerId: type: string description: >- New provider ID (prv_…). Rejected on EHRs where this is a care-team edit. facilityId: type: string description: New facility ID (fac_…) RescheduleAppointmentSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/RescheduledAppointmentResponse' required: - code - data PublicApiBadRequestResponse: type: object properties: code: type: string description: Error code example: bad_request message: type: string description: Human-readable error message example: '''id'' must be a valid UUID' trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiUnauthorizedResponse: type: object properties: code: type: string description: Error code example: unauthorized message: type: string description: Human-readable error message example: Invalid or missing API key trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiForbiddenResponse: type: object properties: code: type: string description: Error code example: forbidden message: type: string description: Human-readable error message example: Insufficient scope trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiNotFoundResponse: type: object properties: code: type: string description: Error code example: not_found message: type: string description: Human-readable error message example: Resource not found trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiConflictResponse: type: object properties: code: type: string description: Error code example: conflict message: type: string description: Human-readable error message example: Cannot edit a signed note trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiRateLimitResponse: type: object properties: code: type: string description: Error code example: rate_limit_exceeded message: type: string description: Human-readable error message example: Rate limit exceeded. Maximum 1000 requests per 60 seconds. trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiBadGatewayResponse: type: object properties: code: type: string description: Error code example: unexpected_integration_error message: type: string description: Human-readable error message example: EHR sync failed trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiServiceUnavailableResponse: type: object properties: code: type: string description: Error code example: server_unresponsive message: type: string description: Human-readable error message example: EHR integration is not available for this note trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id RescheduledAppointmentResponse: type: object properties: id: type: string description: >- The appointment's Max AI id. Normally the id you sent. On a cancel-plus-create EHR it can differ if our sync had already mirrored the new EHR record under its own row — the two converge onto that row, and THIS is the id to use from now on. example: apt_e5f6a7b8c9d04e1f2a3b4c5d6e7f8a9b externalId: type: string description: >- The EHR's appointment id AFTER the move. `null` when the appointment had not yet been written to the EHR — that move amends the QUEUED write rather than moving anything at the vendor, so no vendor id exists on either side of it. nullable: true example: '9938272' previousExternalId: type: string description: >- The EHR's appointment id BEFORE the move. Differs from `externalId` on cancel-plus-create EHRs. `null` when the appointment had not yet been written to the EHR. nullable: true example: '9938271' implementedAsCancelAndCreate: type: boolean description: >- `true` when the EHR implemented the move as cancel-plus-create. The previous EHR record is a tombstone — do not address it again. example: false startsAt: type: string example: '2026-08-05T10:30:00-04:00' status: type: string example: scheduled syncStatus: type: string description: >- `synced` when the move reached the EHR in this request. `pending` when the appointment was still queued and its QUEUED write was amended instead — the move is durable and the ledger unit has moved with it, but the vendor has not been told yet. Wait for `appointment.confirmed`. example: synced enum: - pending - syncing - synced - failed required: - id - externalId - previousExternalId - implementedAsCancelAndCreate - startsAt - status - syncStatus securitySchemes: api-key: scheme: bearer bearerFormat: JWT type: http description: Marketplace API key ````