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

# Overview

> Build server-side integrations with the Cicini Public API v1

# Cicini Public API

Welcome. The **Public API v1** is a **read-only**, **API-key** authenticated HTTP API for organization data. Use it to sync customers and appointments into your own tools (CRMs, analytics, back-office scripts).

<CardGroup cols={2}>
  <Card title="Getting started" icon="rocket" href="/guides/getting-started">
    Base URL, first request, and response shape.
  </Card>

  <Card title="Authentication" icon="key" href="/guides/authentication">
    Bearer keys (`cic_test_` / `cic_live_`) and plan requirements.
  </Card>

  <Card title="Core resources" icon="database" href="/resources/customers">
    Customers and appointments (bookings) that ship today.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference">
    Interactive OpenAPI for every public v1 operation.
  </Card>
</CardGroup>

## What you can build today

| Resource     | Method | Path                          | Notes                                                                |
| ------------ | ------ | ----------------------------- | -------------------------------------------------------------------- |
| Customers    | `GET`  | `/api/public/v1/customers`    | Active customers only; paginated                                     |
| Appointments | `GET`  | `/api/public/v1/appointments` | Active appointments; filters for status, customer, staff, date range |

Machine-readable contract: [OpenAPI](https://cicini.com/openapi.json) (regenerate with `pnpm docs:openapi` in the monorepo).

## Quick mental model

```mermaid theme={null}
sequenceDiagram
  participant App as Your backend
  participant API as Cicini Public API
  participant DB as Org data
  App->>API: Authorization Bearer cic_…
  API->>API: Verify API key → orgId
  API->>DB: Query scoped to orgId
  DB-->>API: Rows
  API-->>App: data[] + pagination
```

1. Create an API key in the Cicini dashboard (**Professional+** plan — see [Authentication](/guides/authentication)).
2. Call public endpoints from a **server** with `Authorization: Bearer …`.
3. Page through results with `limit` / `offset` and `pagination.hasMore`.

## Product truth (do not assume)

| Topic                                    | Truth                                                                                          |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| API surface                              | **Only** paths under `/api/public/v1/*` are integration-friendly                               |
| Write APIs                               | **Not available** on public v1 (no create/update/delete customers or appointments via API key) |
| Services / staff / gift cards / webhooks | **Not** public v1 endpoints yet                                                                |
| Dashboard session APIs                   | `/api/*` used by the web app require NextAuth — **not** for third-party integrations           |
| Super-admin APIs                         | `/api/admin/*` — platform only                                                                 |
| List prices (product)                    | Free $0 · Starter **$19\*\* · Professional **\$49** (`lib/pricing/plan-core.ts`)               |
| API access on Free / Starter             | `apiAccess: false`, `apiKeys: 0` — keys are a **Professional+** feature                        |

## Where to read these docs

| Surface        | URL                                                                     |
| -------------- | ----------------------------------------------------------------------- |
| **Production** | [https://docs.cicini.com](https://docs.cicini.com) (this Mintlify site) |
| App landing    | [https://cicini.com/docs](https://cicini.com/docs) — points here        |
| Local preview  | `pnpm docs:dev` from the monorepo root (`developer-docs/`)              |

## Next steps

* [Getting started](/guides/getting-started)
* [Public vs internal surface](/guides/api-surface)
* [Examples (curl)](/examples/curl)