> ## Documentation Index
> Fetch the complete documentation index at: https://build.practicehub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List appointments



## OpenAPI

````yaml /openapi.json get /appointments
openapi: 3.0.3
info:
  title: PracticeHub API
  version: 1.0.0
  description: >
    The canonical PracticeHub REST API. Every clinic account is a tenant
    addressed by the host the practice signs in on:
    `https://{clinic}.{region}.practicehub.io` (region host `neptune` London,
    `mercury` Frankfurt, `vulcan` Ohio, `jupiter` Singapore, `apollo` Sydney).


    ## Filtering

    List endpoints accept `?attribute=operator:value` with operators `eq`, `ne`,
    `gt`, `gte`, `lt`, `lte`, `null`, `not-null`, `like`, `contains`, `in`,
    `not-in`, `between` (`null`/`not-null` take no value; `in`, `not-in`,
    `between` take comma-separated values; `contains` is a case-insensitive
    substring match with no wildcards to escape). A value with no operator is an
    equality match. Only attributes marked filterable may be filtered (422
    otherwise).


    ## Metadata

    Every record carries an integrator-owned `metadata` object of string, number
    or boolean values (max 50 keys). Send `metadata` on create/update to merge
    keys (`null` removes a key) and filter with `?metadata[key]=operator:value`.


    ## Sorting & pagination

    `?sort=attr[,attr]:asc|desc` on sortable attributes; `?page=` and
    `?page_size=` (max 100). List responses wrap rows in `data` with `links` and
    `meta`.
servers:
  - url: https://{clinic}.{region}.practicehub.io/v3/api
    description: PracticeHub API — the host the practice signs in on
    variables:
      clinic:
        default: your-clinic
        description: The clinic subdomain
      region:
        default: neptune
        enum:
          - neptune
          - mercury
          - vulcan
          - jupiter
          - apollo
        description: >-
          The region host from the practice login URL: neptune (London), mercury
          (Frankfurt), vulcan (Ohio), jupiter (Singapore), apollo (Sydney)
security:
  - bearerAuth: []
tags:
  - name: Utility
    description: Liveness, identity and discovery
  - name: Availability
    description: Free, bookable slots — check before creating an appointment
  - name: Addresses
    description: The addresses resource
  - name: AppointmentTypes
    description: The appointment_types resource
  - name: Appointments
    description: The appointments resource
  - name: DeletedEntities
    description: The deleted_entities resource
  - name: Files
    description: The files resource
  - name: Invoices
    description: The invoices resource
  - name: LineItems
    description: The line_items resource
  - name: Locations
    description: The locations resource
  - name: Modalities
    description: The modalities resource
  - name: Numbers
    description: The numbers resource
  - name: PatientLogTags
    description: The patient_log_tags resource
  - name: PatientLogs
    description: The patient_logs resource
  - name: Patients
    description: The patients resource
  - name: PaymentAllocations
    description: The payment_allocations resource
  - name: PaymentMethods
    description: The payment_methods resource
  - name: Payments
    description: The payments resource
  - name: PractitionerAvailabilities
    description: The practitioner_availabilities resource
  - name: Practitioners
    description: The practitioners resource
  - name: ReferralSources
    description: The referral_sources resource
  - name: Resources
    description: The resources resource
paths:
  /appointments:
    get:
      tags:
        - Appointments
      summary: List appointments
      operationId: list_appointments
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
          description: >-
            Offset pagination is bounded at page 10000 (higher values are
            clamped — meta.current_page reports the page served); use cursor
            pagination for deeper walks.
        - name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          schema:
            type: string
          description: >-
            Cursor pagination: send empty to start, then the token from
            links.next. Constant cost per page and stable under concurrent
            writes; response meta is {per_page, has_more} and links.first/prev
            are null. Bound to the filters, sort and page_size it was issued for
            (422 otherwise). Omit to use page/page_size.
        - name: sort
          in: query
          description: >-
            attr[,attr]:asc|desc — sortable: id, appointment_type_id,
            practitioner_id, patient_id, location_id, status, updated, created
          schema:
            type: string
        - name: id
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: appointment_type_id
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: practitioner_id
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: resource_id
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: columns
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: patient_id
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: location_id
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: start
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: end
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: status
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: note
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: is_group
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: group_master_id
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: group_total_attendees
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: cancel_date
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: cancel_note
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: updated
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: created
          in: query
          description: 'Filter: operator:value'
          schema:
            type: string
        - name: metadata
          in: query
          style: deepObject
          explode: true
          description: 'Filter by integrator metadata: metadata[key]=operator:value'
          schema:
            type: object
            additionalProperties:
              type: string
      responses:
        '200':
          description: Page of appointments
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Appointments'
                  links:
                    $ref: '#/components/schemas/PageLinks'
                  meta:
                    $ref: '#/components/schemas/PageMeta'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    Appointments:
      type: object
      properties:
        id:
          type: integer
        appointment_type_id:
          type: integer
        practitioner_id:
          type: integer
        resource_id:
          type: integer
        columns:
          type: integer
        patient_id:
          type: integer
        location_id:
          type: integer
        start:
          type: string
          format: date-time
          description: Format Y-m-d H:i:s
        end:
          type: string
          format: date-time
          description: Format Y-m-d H:i:s
        status:
          type: string
          enum:
            - pending
        note:
          type: string
          nullable: true
          maxLength: 1000
        is_group:
          type: string
        group_master_id:
          type: integer
        group_total_attendees:
          type: string
        cancel_date:
          type: string
        cancel_note:
          type: string
          nullable: true
          maxLength: 1000
        updated:
          type: string
        created:
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
    PageLinks:
      type: object
      properties:
        first:
          type: string
          nullable: true
        prev:
          type: string
          nullable: true
        next:
          type: string
          nullable: true
    PageMeta:
      type: object
      properties:
        current_page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        last_page:
          type: integer
    Metadata:
      type: object
      description: >-
        Integrator-owned key/value metadata (max 50 keys). Values are strings
        (≤500 chars), numbers or booleans and read back with the type they were
        written with. On write, a null value removes the key. Filter with
        metadata[key]=op:value; number operands compare numerically.
      additionalProperties:
        nullable: true
        oneOf:
          - type: string
            maxLength: 500
          - type: number
          - type: boolean
    Error:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: Human-readable; may change — do not parse
        code:
          type: string
          description: >-
            Stable machine-readable code (snake_case), e.g. validation_failed,
            not_found, key_read_only, slot_unavailable, not_online_bookable,
            group_full, appointment_rule, billing_rule, idempotency_key_reused,
            rate_limited
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Present on validation failures, keyed by attribute
  responses:
    Unauthenticated:
      description: Missing or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Invalid input; `errors` is keyed by attribute
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key from Developers → API Keys, sent as Authorization: Bearer <key>.'

````