> ## 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. # Cancel an appointment > Cancels an appointment. If the EHR write for it is still queued, this resolves entirely locally and nothing is sent to the EHR — there is nothing there to cancel — and `syncStatus` comes back `cancelled_before_sync`. If a write is in flight, the cancel is recorded and the writer takes the appointment back off the calendar: `status` is `cancelling`, and `appointment.cancelled` follows. Otherwise it is cancelled at the EHR in this request. An unresolved move or cancellation returns 409. A lost vendor response returns `ehr_write_uncertain` with `requiresReconciliation: true`; verify the outcome before attempting another change. ## OpenAPI ````yaml /openapi-v4.json post /appointments/{id}/cancel 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}/cancel: post: tags: - Appointments summary: Cancel an appointment description: >- Cancels an appointment. If the EHR write for it is still queued, this resolves entirely locally and nothing is sent to the EHR — there is nothing there to cancel — and `syncStatus` comes back `cancelled_before_sync`. If a write is in flight, the cancel is recorded and the writer takes the appointment back off the calendar: `status` is `cancelling`, and `appointment.cancelled` follows. Otherwise it is cancelled at the EHR in this request. An unresolved move or cancellation returns 409. A lost vendor response returns `ehr_write_uncertain` with `requiresReconciliation: true`; verify the outcome before attempting another change. operationId: AppointmentsPublicController_cancelAppointment parameters: - name: id required: true in: path description: Appointment ID 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/CancelAppointmentBody' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CancelAppointmentSuccessResponse' '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: CancelAppointmentBody: type: object properties: reasonId: type: string description: >- Cancellation reason `externalId` from GET /appointments/cancel-reasons. Ignored on EHRs with no reason catalogue. note: type: string description: Free-text cancellation note, where the EHR stores one CancelAppointmentSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/CancelledAppointmentResponse' 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 CancelledAppointmentResponse: type: object properties: id: type: string example: apt_e5f6a7b8c9d04e1f2a3b4c5d6e7f8a9b status: type: string description: >- `cancelled` once resolved. `cancelling` while an in-flight write or its queued follow-up cancellation is being resolved — the cancel is recorded and the writer will take the appointment back off the calendar; watch `appointment.cancelled`. example: cancelled enum: - cancelled - cancelling syncStatus: type: string description: >- `synced` when the cancellation reached the EHR. `cancelled_before_sync` when the appointment had never been written — nothing was sent, because there was nothing there to cancel. `syncing` while a write or its queued follow-up cancellation awaits completion. example: synced enum: - synced - cancelled_before_sync - syncing required: - id - status - syncStatus securitySchemes: api-key: scheme: bearer bearerFormat: JWT type: http description: Marketplace API key ````