> ## Documentation Index > Fetch the complete documentation index at: https://docs.clinikehr.com/llms.txt > Use this file to discover all available pages before exploring further. # List appointments > **Permission:** `appointments:read` List appointments. A restricted patient's appointment is excluded. Date range clamped to 366 days. ## OpenAPI ````yaml /openapi/ehr-api.v1.yaml get /v1/clinics/{clinic_id}/appointments openapi: 3.1.0 info: title: ClinikEHR API version: 1.0.0 description: >- Server-to-server REST API for a clinic's own data, reached with a key the clinic (or a developer workspace) creates in the developer portal. Authenticate every request with `Authorization: Bearer `. Test keys reach only your workspace's own synthetic sandbox; live keys reach the clinic that created them. Lists wrap their rows as `{ data, has_more, next_cursor }`; single resources are returned directly. Errors are `application/problem+json` (RFC 9457) with a stable `code`. Write requests accept an `Idempotency-Key` header so a retry never repeats a change. See the guides for authentication, permissions, pagination, rate limits and retries. servers: - url: https://api.clinikehr.com security: - ApiKey: [] paths: /v1/clinics/{clinic_id}/appointments: get: tags: - Appointments summary: List appointments description: >- **Permission:** `appointments:read` List appointments. A restricted patient's appointment is excluded. Date range clamped to 366 days. operationId: listAppointments parameters: - name: clinic_id in: path required: true schema: type: string format: uuid - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 25 - name: starting_after in: query required: false schema: type: string - name: updated_since in: query required: false schema: type: string format: date-time - name: patient_id in: query required: false schema: type: string format: uuid - name: clinician_id in: query required: false schema: type: string format: uuid - name: status in: query required: false schema: type: string enum: - scheduled - confirmed - in_progress - completed - cancelled - no_show - rescheduled - name: from in: query required: false schema: type: string format: date - name: to in: query required: false schema: type: string format: date responses: '200': description: OK. content: application/json: schema: type: object required: - data - has_more - next_cursor properties: data: type: array items: $ref: '#/components/schemas/Appointment' has_more: type: boolean next_cursor: type: - string - 'null' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' security: - ApiKey: [] components: schemas: Appointment: type: object description: >- Never present here, by name: client_appointment_date/client_start_time/ client_end_time/client_timezone, form_data, custom_color, provider_user_id, time_range, excluded_from_overlap_check, booking_identity_review, provider_busy_minutes, out_of_office_confirmed_at, booking_confirmation_deferred, clinic_id. required: - id - status properties: id: type: string format: uuid patient_id: type: - string - 'null' format: uuid service_id: type: - string - 'null' format: uuid clinician_id: type: - string - 'null' format: uuid description: clinic_staff.id — never provider_user_id. start_at: type: - string - 'null' format: date-time end_at: type: - string - 'null' format: date-time description: Derived from the service's duration — never independent input. duration_minutes: type: - integer - 'null' timezone: type: - string - 'null' venue_type: type: - string - 'null' enum: - physical - online - mobile_clinic - null venue_details: type: - object - 'null' description: Read-only. status: type: string enum: - scheduled - confirmed - in_progress - completed - cancelled - no_show - rescheduled booking_source: type: - string - 'null' description: Always "api" for a row this API created. patient_notes: type: - string - 'null' clinic_notes: type: - string - 'null' symptoms_description: type: - string - 'null' urgency_level: type: - string - 'null' enum: - low - normal - high - emergency - null ai_category: type: - string - 'null' description: Read-only. ai_priority_score: type: - number - 'null' description: Read-only. ai_suggested_duration: type: - number - 'null' description: Read-only. predicted_show_probability: type: - number - 'null' description: Read-only. confirmation_sent_at: type: - string - 'null' format: date-time confirmation_method: type: - string - 'null' reminder_sent_at: type: - string - 'null' format: date-time reminder_method: type: - string - 'null' reminder_sent: type: - boolean - 'null' payment_status: type: - string - 'null' enum: - pending - paid - partial - refunded - waived - failed - null payment_method: type: - string - 'null' payment_amount: type: - number - 'null' payment_due_date: type: - string - 'null' format: date amount_paid: type: - number - 'null' description: Read-only. payment_id: type: - string - 'null' description: Read-only. confirmation_code: type: - string - 'null' description: Read-only. cancellation_reason: type: - string - 'null' cancelled_at: type: - string - 'null' format: date-time completed_at: type: - string - 'null' format: date-time is_group_appointment: type: - boolean - 'null' description: Read-only. max_participants: type: - integer - 'null' description: Read-only. group_name: type: - string - 'null' description: Read-only. recurrence_pattern_id: type: - string - 'null' format: uuid description: Read-only. Creating/editing a whole series is refused. series_id: type: - string - 'null' format: uuid description: Read-only. series_index: type: - integer - 'null' description: Read-only. email_notifications: type: - boolean - 'null' sms_notifications: type: - boolean - 'null' voice_notifications: type: - boolean - 'null' notes_session_ids: type: array items: type: string format: uuid description: Read-only. class_session_id: type: - string - 'null' format: uuid description: Read-only. self_reschedule_count: type: - integer - 'null' description: >- Read-only. Tracks PATIENT-initiated portal reschedules only — never incremented by this API. location_id: type: - string - 'null' format: uuid participants: type: array items: $ref: '#/components/schemas/AppointmentParticipant' description: Read-only group roster — group creation is a scope cut in v1. created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time AppointmentParticipant: type: object properties: patient_id: type: - string - 'null' format: uuid status: type: - string - 'null' Problem: type: object description: RFC 9457 application/problem+json. required: - type - title - status - code - request_id properties: type: type: string format: uri title: type: string status: type: integer detail: type: string code: type: string request_id: type: string errors: type: array items: type: object required: - pointer - message properties: pointer: type: string message: type: string responses: BadRequest: description: >- The request failed validation (unknown query parameter, limit out of range, malformed body). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unauthorized: description: >- Missing, malformed, unknown, revoked or expired key, or the wrong secret. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: >- The key or connection lacks the required scope, the plan does not include this resource, the request came from an address this key's IP allow-list does not permit, a TEST-environment workspace key asked for a clinic_id other than its own workspace's sandbox (`sandbox_only`), or a LIVE workspace key asked for a real clinic while its workspace's verification has lapsed (`not_verified`) — the response never names which addresses ARE allowed, nor which clinic actually is the sandbox. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' NotFound: description: The record is absent, or out of the key's scope — one message for both. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' TooManyRequests: description: Rate limited. See the Retry-After header. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: ehr_live__ or ehr_test__ ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.