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

# List appointments

> Returns a paginated list of active appointments for the organization associated with the API key. Supports status, customer, staff, and date filters.



## OpenAPI

````yaml /openapi.json get /api/public/v1/appointments
openapi: 3.1.0
info:
  title: Cicini Public API
  version: 1.0.0
  description: >-
    Read-only Public API v1 for organization data. Authenticate with an
    organization API key (`cic_test_…` or `cic_live_…`). Current operations:
    list customers, list appointments. Dashboard/admin routes are not part of
    this contract. API key management requires Professional+ (plan-core
    `apiAccess`). Developer guides: https://docs.cicini.com (Mintlify; source
    developer-docs/).
  contact:
    name: Cicini
    url: https://cicini.com
servers:
  - url: https://cicini.com
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Customers
    description: Customer directory (read-only)
  - name: Appointments
    description: Appointments / reservations (read-only)
paths:
  /api/public/v1/appointments:
    get:
      tags:
        - Appointments
      summary: List appointments
      description: >-
        Returns a paginated list of active appointments for the organization
        associated with the API key. Supports status, customer, staff, and date
        filters.
      operationId: listAppointments
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            description: 'Max items to return (1–100). Default: 50.'
            example: 50
          required: false
          description: 'Max items to return (1–100). Default: 50.'
          name: limit
          in: query
        - schema:
            type:
              - integer
              - 'null'
            minimum: 0
            description: 'Number of items to skip. Default: 0.'
            example: 0
          required: false
          description: 'Number of items to skip. Default: 0.'
          name: offset
          in: query
        - schema:
            type: string
            enum:
              - scheduled
              - confirmed
              - checked_in
              - no_show
              - cancelled
              - completed
            description: Filter by appointment status.
          required: false
          description: Filter by appointment status.
          name: status
          in: query
        - schema:
            type: string
            description: Filter by customer id.
          required: false
          description: Filter by customer id.
          name: customerId
          in: query
        - schema:
            type: string
            description: Filter by staff id.
          required: false
          description: Filter by staff id.
          name: staffId
          in: query
        - schema:
            type: string
            format: date-time
            description: Inclusive lower bound (ISO-8601) on start time.
          required: false
          description: Inclusive lower bound (ISO-8601) on start time.
          name: startDate
          in: query
        - schema:
            type: string
            format: date-time
            description: Inclusive upper bound (ISO-8601) on start time.
          required: false
          description: Inclusive upper bound (ISO-8601) on start time.
          name: endDate
          in: query
      responses:
        '200':
          description: Paginated appointment list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        orgId:
                          type: string
                        customerId:
                          type: string
                        staffId:
                          type: string
                        serviceId:
                          type: string
                        start:
                          type: string
                          description: ISO-8601 start time
                        end:
                          type: string
                          description: ISO-8601 end time
                        status:
                          type: string
                        locationType:
                          type: string
                        resourceId:
                          type: string
                        priceCents:
                          type: integer
                        currency:
                          type: string
                        note:
                          type: string
                        paymentStatus:
                          type: string
                        amountPaidCents:
                          type:
                            - integer
                            - 'null'
                        paymentKind:
                          type:
                            - string
                            - 'null'
                        paymentId:
                          type:
                            - string
                            - 'null'
                        invoiceId:
                          type:
                            - string
                            - 'null'
                        requiresPayment:
                          type: boolean
                        confirmedAfterPayment:
                          type: boolean
                        dayKey:
                          type: string
                        createdAt:
                          anyOf:
                            - type: string
                            - type: string
                              format: date-time
                        updatedAt:
                          anyOf:
                            - type: string
                            - type: string
                              format: date-time
                      required:
                        - id
                        - start
                        - end
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
                      total:
                        type: integer
                      hasMore:
                        type: boolean
                    required:
                      - limit
                      - offset
                      - total
                      - hasMore
                required:
                  - data
                  - pagination
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  details: {}
                required:
                  - error
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  details: {}
                required:
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  details: {}
                required:
                  - error
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Organization API key. Prefix with `Bearer `. Test keys start with
        `cic_test_`; live keys with `cic_live_`.

````