openapi: 3.0.3
info:
  title: Cliniko Appointment Types Appointments API
  description: 'Cliniko is practice management software for allied health practices and clinics. This is a representative subset of the public Cliniko REST API, grounded in the official documentation at https://docs.api.cliniko.com and the redguava/cliniko-api GitHub repository. It is not the complete surface - Cliniko documents 50+ resources (appointment types, attendees, availability blocks, billable items, bookings, businesses, communications, concession types, contacts, group appointments, individual appointments, invoices, invoice items, medical alerts, patients, patient attachments, patient cases, patient forms, practitioners, products, recalls, referral sources, services, settings, stock adjustments, taxes, treatment notes, users, and more).

    Base URL is region-sharded. The shard is the suffix on your API key (for example a key ending `-uk1` is served from `https://api.uk1.cliniko.com`); keys with no suffix belong to the `au1` shard. All paths are prefixed with `/v1`.

    Authentication is HTTP Basic: the API key is the username and the password is empty (`-u API_KEY:`). Every request MUST also send an `Accept: application/json` header and a `User-Agent` header of the form `APP_VENDOR_NAME (APP_VENDOR_EMAIL)` containing a valid contact email, or requests may be automatically blocked. Requests are rate limited to 200 per minute per user; a `429` response includes an `X-RateLimit-Reset` header with a UNIX timestamp.

    Modeled note - the field sets below are drawn from the documented example responses; some optional attributes may be omitted, and request-body schemas are representative rather than exhaustive.'
  version: v1
  contact:
    name: Cliniko API Support
    url: https://docs.api.cliniko.com/
  license:
    name: Proprietary
    url: https://www.cliniko.com/terms/
servers:
- url: https://api.{shard}.cliniko.com/v1
  description: Cliniko region-sharded API. The shard is the suffix on your API key.
  variables:
    shard:
      default: au1
      enum:
      - au1
      - au2
      - au3
      - au4
      - uk1
      - eu1
      - us1
      - ca1
      description: Region shard derived from the API key suffix. Keys without a suffix use au1.
security:
- basicAuth: []
tags:
- name: Appointments
  description: Individual appointments and the unified bookings feed.
paths:
  /individual_appointments:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    get:
      operationId: listIndividualAppointments
      tags:
      - Appointments
      summary: Get individual appointments
      description: Returns a paginated list of individual appointments.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of individual appointments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  individual_appointments:
                    type: array
                    items:
                      $ref: '#/components/schemas/IndividualAppointment'
                  total_entries:
                    type: integer
                  links:
                    $ref: '#/components/schemas/Links'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createIndividualAppointment
      tags:
      - Appointments
      summary: Create individual appointment
      description: Books a new individual appointment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndividualAppointmentInput'
      responses:
        '201':
          description: The created appointment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndividualAppointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /individual_appointments/{id}:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getIndividualAppointment
      tags:
      - Appointments
      summary: Get individual appointment
      description: Returns a single individual appointment by ID.
      responses:
        '200':
          description: The requested appointment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndividualAppointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateIndividualAppointment
      tags:
      - Appointments
      summary: Update individual appointment
      description: Updates an existing individual appointment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndividualAppointmentInput'
      responses:
        '200':
          description: The updated appointment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndividualAppointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /individual_appointments/{id}/cancel:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    - $ref: '#/components/parameters/Id'
    patch:
      operationId: cancelIndividualAppointment
      tags:
      - Appointments
      summary: Cancel individual appointment
      description: Cancels an individual appointment, optionally with a cancellation reason.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                cancellation_reason:
                  type: integer
                  description: Numeric cancellation reason code.
                cancellation_note:
                  type: string
      responses:
        '200':
          description: The cancelled appointment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndividualAppointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /individual_appointments/{id}/conflicts:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getIndividualAppointmentConflicts
      tags:
      - Appointments
      summary: Get appointment conflicts
      description: Returns whether the specified individual appointment has scheduling conflicts.
      responses:
        '200':
          description: Conflict information for the appointment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  conflicts:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /bookings:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    get:
      operationId: listBookings
      tags:
      - Appointments
      summary: Get bookings
      description: Returns a paginated list of bookings. Bookings is a convenience feed that can return group appointments, individual appointments, and unavailable blocks; the shape of each object depends on its type.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of bookings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  bookings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Booking'
                  total_entries:
                    type: integer
                  links:
                    $ref: '#/components/schemas/Links'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /bookings/{id}:
    parameters:
    - $ref: '#/components/parameters/UserAgent'
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getBooking
      tags:
      - Appointments
      summary: Get booking
      description: Returns a single booking by ID.
      responses:
        '200':
          description: The requested booking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests. The API is limited to 200 requests per minute per user. The X-RateLimit-Reset header carries a UNIX timestamp for when the window resets.
      headers:
        X-RateLimit-Reset:
          description: UNIX timestamp when the rate-limit window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: string
    PerPage:
      name: per_page
      in: query
      required: false
      description: Items per page. Default 50, maximum 100.
      schema:
        type: integer
        default: 50
        maximum: 100
    UserAgent:
      name: User-Agent
      in: header
      required: true
      description: Must be of the form `APP_VENDOR_NAME (APP_VENDOR_EMAIL)` and include a valid contact email. Requests without a compliant User-Agent may be automatically blocked.
      schema:
        type: string
        example: MyClinicApp (dev@myclinic.example)
    Page:
      name: page
      in: query
      required: false
      description: Page number (pagination).
      schema:
        type: integer
        default: 1
  schemas:
    IndividualAppointment:
      type: object
      properties:
        id:
          type: integer
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        patient_name:
          type: string
        notes:
          type: string
          nullable: true
        did_not_arrive:
          type: boolean
        patient_arrived:
          type: boolean
        email_reminder_sent:
          type: boolean
        sms_reminder_sent:
          type: boolean
        cancelled_at:
          type: string
          format: date-time
          nullable: true
        cancellation_note:
          type: string
          nullable: true
        cancellation_reason:
          type: integer
          nullable: true
        cancellation_reason_description:
          type: string
        invoice_status:
          type: integer
          nullable: true
        treatment_note_status:
          type: integer
          nullable: true
        repeat_rule:
          type: object
          additionalProperties: true
        repeats:
          type: string
          nullable: true
        deleted_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        appointment_type:
          $ref: '#/components/schemas/Reference'
        business:
          $ref: '#/components/schemas/Reference'
        practitioner:
          $ref: '#/components/schemas/Reference'
        patient:
          $ref: '#/components/schemas/Reference'
        conflicts:
          $ref: '#/components/schemas/Reference'
        links:
          $ref: '#/components/schemas/Links'
    Reference:
      type: object
      description: A link to a related resource.
      properties:
        links:
          type: object
          properties:
            self:
              type: string
              format: uri
    IndividualAppointmentInput:
      type: object
      required:
      - starts_at
      - ends_at
      - patient_id
      - practitioner_id
      - business_id
      - appointment_type_id
      properties:
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        patient_id:
          type: string
        practitioner_id:
          type: string
        business_id:
          type: string
        appointment_type_id:
          type: string
        notes:
          type: string
    Links:
      type: object
      description: HAL-style pagination and self links.
      properties:
        self:
          type: string
          format: uri
        next:
          type: string
          format: uri
        previous:
          type: string
          format: uri
    Booking:
      type: object
      description: A booking may represent an individual appointment, a group appointment, or an unavailable block; fields present vary by type.
      properties:
        id:
          type: integer
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        notes:
          type: string
          nullable: true
        max_attendees:
          type: integer
        patient_ids:
          type: array
          items:
            type: integer
        repeat_rule:
          type: object
          additionalProperties: true
        deleted_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        appointment_type:
          $ref: '#/components/schemas/Reference'
        business:
          $ref: '#/components/schemas/Reference'
        practitioner:
          $ref: '#/components/schemas/Reference'
        conflicts:
          $ref: '#/components/schemas/Reference'
        links:
          $ref: '#/components/schemas/Links'
    Error:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties: true
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic authentication. The API key is the username and the password is left empty (curl: `-u API_KEY:`). The shard suffix on the key selects the base host.'