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

# Getting started

> Base URL, first request, and how to page through Public API v1

# Getting started

The Cicini Public API is a **read-only**, **API key** authenticated HTTP API for organization data.

## Base URL

| Environment       | Base URL                |
| ----------------- | ----------------------- |
| Production        | `https://cicini.com`    |
| Local development | `http://localhost:3000` |

All paths are relative to that base (for example `/api/public/v1/customers`).

## Prerequisites

1. A Cicini organization on a plan with **API access** (Professional or Enterprise — Free and Starter cannot create API keys).
2. An API key created in the dashboard under **Settings → Integrations → API keys** (`cic_test_…` or `cic_live_…`).
3. A backend or CLI that can send `Authorization: Bearer …` (never embed live keys in a browser SPA).

## First request

```bash theme={null}
export CICINI_API_KEY="cic_test_YOUR_KEY"
export CICINI_BASE_URL="https://cicini.com"   # or http://localhost:3000

curl -sS \
  -H "Authorization: Bearer $CICINI_API_KEY" \
  -H "Accept: application/json" \
  "$CICINI_BASE_URL/api/public/v1/customers?limit=10"
```

### Success shape

```json theme={null}
{
  "data": [
    {
      "id": "clx…",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "displayName": "Ada Lovelace",
      "email": "ada@example.com"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 42,
    "hasMore": true
  }
}
```

### Failure example (missing key)

```json theme={null}
{
  "error": "Unauthorized",
  "message": "API key required in Authorization header"
}
```

Status: **401**.

## Conventions

| Convention  | Detail                                                            |
| ----------- | ----------------------------------------------------------------- |
| Protocol    | HTTPS in production                                               |
| Format      | JSON request/response; `Accept: application/json`                 |
| Auth        | `Authorization: Bearer <api_key>` only                            |
| Time fields | ISO-8601 strings (for example `2026-07-19T15:00:00.000Z`)         |
| Money       | Integer **cents** where present (`priceCents`, `amountPaidCents`) |
| Org scope   | Inferred from the API key — you never pass `orgId` on public v1   |

## Pagination (summary)

| Query    | Default | Limits            |
| -------- | ------- | ----------------- |
| `limit`  | `50`    | Integer **1–100** |
| `offset` | `0`     | Integer ≥ 0       |

Loop while `pagination.hasMore` is `true`, increasing `offset` by `limit`. Full guide: [Pagination](/guides/pagination).

## What to call next

| Goal                | Endpoint                                                                |
| ------------------- | ----------------------------------------------------------------------- |
| Sync CRM contacts   | [`GET /api/public/v1/customers`](/resources/customers)                  |
| Export schedule     | [`GET /api/public/v1/appointments`](/resources/appointments)            |
| Understand failures | [Errors](/guides/errors)                                                |
| Plan / rate honesty | [Rate limits](/guides/rate-limits) · [API surface](/guides/api-surface) |

Interactive parameter docs: **API Reference** tab (OpenAPI playground).