# Servicify Appointments

> Shopify app for booking events, services, and appointments. Exposes a 1st-party REST API ("Agent API") that lets LLM agents and external tools manage events, bookings, employees, and availability on behalf of merchants.

## Agent API

- [OpenAPI 3.1 spec](https://app.getservicify.com/api/public/v1/openapi.json): machine-readable contract for the entire API.
- [Interactive reference](https://app.getservicify.com/api/public/v1/docs): human-browsable docs rendered from the spec.
- [Capability discovery](https://app.getservicify.com/api/public/v1/me): authenticated GET that returns the shop, plan, granted scopes, and server time. Recommended first call.

## Authentication

Bearer token of the form `srv_live_...`, minted per-shop. Plan-gated to the Ultimate tier. Merchants create and revoke keys at Settings → API access in the embedded admin UI. Send as `Authorization: Bearer <token>`.

## Conventions

- Errors are returned as `{ "error": { "code": "...", "message": "..." } }`.
- Write endpoints accept an `Idempotency-Key` header; it is required on `POST /bookings`. Replaying with the same key and body returns the original response; replaying with a different body returns 409.
- Pagination differs per endpoint, so check the spec rather than assuming:
  - `GET /events` is cursor-paginated: `?cursor=<id>&limit=<n>` (default 50, max 200), response includes `nextCursor` and `hasMore`.
  - `GET /bookings` is page-paginated: `?page=<n>` (1-indexed) and `?limit=<n>` (default 30), response is `{ dates: { results, total }, totalBookings }`.
  - `GET /availability` is unpaginated and returns a bare array.
- Only `GET /reports/peak-hours` is rate limited (30 requests/minute per credential). It returns `X-RateLimit-*` headers and 429 with `Retry-After` when exceeded.