Appointments - Cicini API

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

List appointments

GET /api/public/v1/appointments

Auth: Bearer API key with scope appointments:read
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

{
  "data": [
    {
      "id": "clxappt…",
      "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",
      "createdAt": "2026-07-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "hasMore": false
  }
}

start and end are ISO-8601 strings. Notes, prices, coupons, and calendar ids are not included. 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

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

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
`403`	Missing `appointments:read` (`WWW-Authenticate: Bearer error="insufficient_scope"`) or plan does not allow API access
`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