> ## Documentation Index
> Fetch the complete documentation index at: https://cal.id/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Build on Cal ID — a REST API for scheduling: event types, availability, slots, bookings, teams, contacts, and webhooks.

The Cal ID API is a REST API that lets you manage everything in Cal ID programmatically — event types, availability and schedules, bookable slots, bookings, teams, memberships, contacts, and webhooks. All requests and responses use JSON, and every endpoint is authenticated with an API key.

<Card title="Base URL" icon="server" horizontal>
  All requests are made to `https://api.cal.id`.
</Card>

## Authentication

Cal ID authenticates requests with an **API key** sent as a **Bearer token** in the `Authorization` header.

<Steps>
  <Step title="Create an API key">
    In the Cal ID dashboard, go to **Settings → Developer → API keys** and create a key. Keys are prefixed with `calid_`. See [Get your API key](/docs/developers/api-key) for the full walkthrough.
  </Step>

  <Step title="Send it with every request">
    Include the key in the `Authorization` header:

    ```bash theme={null}
    Authorization: Bearer calid_xxxxx
    ```
  </Step>
</Steps>

<Note>
  To manage a team's resources (team event types, memberships, and schedules), use an API key belonging to a team **owner or admin**.
</Note>

<Warning>
  Your API key grants full access to your account. Keep it secret — never commit it to source control, embed it in client-side code, or share it in public links.
</Warning>

## Quickstart

Retrieve the authenticated user's profile to confirm your key works:

```bash theme={null}
curl https://api.cal.id/users/me \
  -H "Authorization: Bearer calid_xxxxx"
```

## Response format

Every response is a JSON envelope with a consistent shape.

<CodeGroup>
  ```json Success theme={null}
  {
    "success": true,
    "data": { },
    "message": "Request completed successfully",
    "meta": { }
  }
  ```

  ```json Error theme={null}
  {
    "success": false,
    "message": "A human-readable explanation of what went wrong",
    "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" }
  }
  ```
</CodeGroup>

The `data` field holds the resource or resources you requested. On list endpoints, `meta` carries pagination and contextual information.

## Status codes

| Code  | Meaning                                                 |
| ----- | ------------------------------------------------------- |
| `200` | Success                                                 |
| `400` | Bad request — check your parameters                     |
| `401` | Unauthorized — missing or invalid API key               |
| `403` | Forbidden — your key lacks permission for this resource |
| `500` | Something went wrong on Cal ID's side                   |

## Pagination

List endpoints are paginated with `page` and `limit` query parameters, and return the current page details in `meta.pagination`.

```bash theme={null}
curl "https://api.cal.id/booking/?page=1&limit=20" \
  -H "Authorization: Bearer calid_xxxxx"
```

```json theme={null}
{
  "success": true,
  "data": [ ],
  "meta": {
    "pagination": { "page": 1, "limit": 20, "total": 134, "totalPages": 7 }
  }
}
```

<Note>
  A few endpoints (such as **Contacts**) page with `limit` and `offset` instead of `page`. Check each endpoint's parameters.
</Note>

## Filtering and sorting

Most list endpoints accept filters and sort keys as query parameters. For example, [List bookings](/docs/api-reference/booking/list-bookings) supports filtering by `status`, `eventTypeIds`, `attendeeEmail`, and date ranges (`afterStartDate`, `beforeEndDate`, `afterCreatedDate`, …), plus sorting with `sortStart`, `sortCreated`, and `sortUpdated`. See each endpoint's **Query Parameters** for the full set.

## Next steps

<CardGroup cols={2}>
  <Card title="Get your API key" icon="key" href="/docs/developers/api-key">
    Create and manage the keys that authenticate your requests.
  </Card>

  <Card title="Find your Event Type ID" icon="hashtag" href="/docs/developers/event-type-id">
    Locate the IDs you'll pass to booking and event-type endpoints.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/developers/webhooks">
    Subscribe to booking and meeting events in real time.
  </Card>

  <Card title="Integration overview" icon="plug" href="/docs/developers/api-integration">
    How the API is structured, from servers to authentication.
  </Card>
</CardGroup>