> ## 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.

# Appointments

> List organization appointments (bookings / reservations) via Public API v1

# Appointments

Read-only access to organization **appointments** (also called reservations/bookings in the product UI).

## List appointments

```http theme={null}
GET /api/public/v1/appointments
```

**Auth:** Bearer API key\
**OpenAPI operationId:** `listAppointments`

### Query parameters

| Name         | Type                       | Default | Description                                                                           |
| ------------ | -------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `limit`      | integer                    | `50`    | Page size (1–100)                                                                     |
| `offset`     | integer                    | `0`     | Rows to skip                                                                          |
| `status`     | string enum                | —       | `scheduled` \| `confirmed` \| `checked_in` \| `no_show` \| `cancelled` \| `completed` |
| `customerId` | string                     | —       | Filter by customer id                                                                 |
| `staffId`    | string                     | —       | Filter by staff id                                                                    |
| `startDate`  | string (ISO-8601 datetime) | —       | Inclusive lower bound on appointment **start**                                        |
| `endDate`    | string (ISO-8601 datetime) | —       | Inclusive upper bound on appointment **start**                                        |

Validated by `publicAppointmentsQuerySchema`.

### Response

```json theme={null}
{
  "data": [
    {
      "id": "clxappt…",
      "orgId": "clxorg…",
      "customerId": "clxcust…",
      "staffId": "clxstaff…",
      "serviceId": "clxsvc…",
      "start": "2026-07-19T15:00:00.000Z",
      "end": "2026-07-19T15:30:00.000Z",
      "status": "confirmed",
      "locationType": "in_person",
      "priceCents": 5000,
      "currency": "cad",
      "note": null,
      "paymentStatus": "paid",
      "amountPaidCents": 5000,
      "requiresPayment": true,
      "createdAt": "2026-07-01T10:00:00.000Z",
      "updatedAt": "2026-07-01T10:05:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "hasMore": false
  }
}
```

`start` and `end` are always ISO-8601 strings in the public response. Money fields are **integer cents** when present. Schema reference: `publicAppointmentSchema`.

### Filters and scope

| Behavior    | Detail                             |
| ----------- | ---------------------------------- |
| Org scope   | Key’s organization only            |
| Soft-delete | Only `isActive: true` appointments |
| Order       | Newest `startAt` first             |
| Date filter | Applied on start time (`startAt`)  |

### Example — week window

```bash theme={null}
curl -sS \
  -H "Authorization: Bearer $CICINI_API_KEY" \
  "https://cicini.com/api/public/v1/appointments?status=confirmed&startDate=2026-07-14T00:00:00.000Z&endDate=2026-07-21T00:00:00.000Z&limit=100"
```

### Example — one customer

```bash theme={null}
curl -sS \
  -H "Authorization: Bearer $CICINI_API_KEY" \
  "https://cicini.com/api/public/v1/appointments?customerId=clxcust…&limit=20"
```

### Errors

| Status | When                                  |
| ------ | ------------------------------------- |
| `400`  | Invalid enum, datetime, or pagination |
| `401`  | Missing or invalid API key            |
| `500`  | Server error                          |

## Not available on public v1

* Create / reschedule / cancel appointments
* Collect payment or apply gift cards via API key
* Calendar ICS export
* Single-resource `GET /appointments/:id`