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

# Calendar API

> Authenticate with scoped API keys to check availability and manage bookings for a subaccount calendar.

## Welcome

The Vapify Calendar API is designed for AI agents, automation tools, and external systems that need to work with a subaccount's scheduling data. With the correct API key, an integration can check availability, retrieve bookings, create appointments, update bookings, and cancel them.

<CardGroup cols={1}>
  <Card title="Calendar Endpoints" icon="calendar" href="/api-reference/calendar-endpoints">
    Full request and response reference for every calendar endpoint
  </Card>
</CardGroup>

<Note>
  This API is the **agent surface**: it covers calendar availability and bookings only. **Contacts are not exposed to this API key** — they're managed from the dashboard under an authenticated session.
</Note>

***

## Get an API key

<Steps>
  <Step title="Open the calendar API keys page">
    From the sidebar, open **Calendar → API Keys**. Only agency owners can create calendar API keys.
  </Step>

  <Step title="Create a key">
    Click **Create API Key**, give it a name, optionally set an expiry, and select the permissions the integration needs (see the permission model below).
  </Step>

  <Step title="Copy the key">
    Copy the plain-text key immediately — it's shown only once. The key is scoped to the selected subaccount.
  </Step>
</Steps>

Full product walkthrough: [Calendar integration](/integrations/calendar).

***

## Base URL

```http theme={null}
https://app.vapify.agency/v1/api
```

## Authentication

All endpoints require an API key in the `x-calendar-api-key` request header.

```http theme={null}
x-calendar-api-key: YOUR_API_KEY
```

<Warning>
  The plain-text API key is only shown once when you create it. Store it securely because it cannot be retrieved later.
</Warning>

***

## Permission Model

Each key is permission-scoped. The key must include the correct permission for the operation being requested.

| UI Label           | Permission ID          | Grants Access To                      |
| ------------------ | ---------------------- | ------------------------------------- |
| Check availability | `canCheckAvailability` | Availability lookup endpoints         |
| Get bookings       | `canGetBookings`       | Booking read endpoints                |
| Book appointments  | `canBook`              | Booking creation and update endpoints |
| Cancel bookings    | `canCancel`            | Booking cancellation endpoints        |

This lets you create narrowly scoped keys for different automation jobs instead of reusing one all-access key everywhere.

***

## Rate Limiting

* **Limit:** 60 requests per minute per API key
* **Window:** Sliding 1-minute window
* **Failure response:** `429 Too Many Requests`

If you are building an AI workflow, add retry logic with backoff instead of sending burst retries.

***

## Endpoint Summary

| Method   | Endpoint                                          | Required Permission    | Purpose                                   |
| -------- | ------------------------------------------------- | ---------------------- | ----------------------------------------- |
| `GET`    | `/calendar/availability`                          | `canCheckAvailability` | Return available time slots               |
| `GET`    | `/calendar/bookings`                              | `canGetBookings`       | List bookings with filters and pagination |
| `GET`    | `/calendar/bookings/:id`                          | `canGetBookings`       | Retrieve a single booking                 |
| `POST`   | `/calendar/event-types/:eventTypeId/bookings`     | `canBook`              | Create a booking                          |
| `PUT`    | `/calendar/event-types/:eventTypeId/bookings/:id` | `canBook`              | Update or reschedule a booking            |
| `DELETE` | `/calendar/bookings/:id`                          | `canCancel`            | Cancel a booking                          |

Continue to [Calendar Endpoints](/api-reference/calendar-endpoints) for field-level request and response examples.

***

## Common Booking Fields

Most booking responses use the same core fields:

| Field         | Type             | Description                                                                          |
| ------------- | ---------------- | ------------------------------------------------------------------------------------ |
| `id`          | integer          | Numeric booking identifier                                                           |
| `uid`         | string           | Unique booking UID when returned                                                     |
| `startTime`   | ISO 8601 string  | Booking start time                                                                   |
| `endTime`     | ISO 8601 string  | Booking end time                                                                     |
| `status`      | string           | Booking state such as `pending`, `confirmed`, `cancelled`, `completed`, or `no_show` |
| `timezone`    | string           | Booking timezone                                                                     |
| `title`       | string           | Booking title                                                                        |
| `description` | string or `null` | Optional notes or description                                                        |
| `location`    | string or `null` | Booking location or meeting URL                                                      |
| `metadata`    | object           | Arbitrary data attached to the booking                                               |
| `attendees`   | array            | Attendee list and attendee metadata                                                  |

***

## Error Format

Calendar API errors use a simple JSON body:

```json theme={null}
{
  "statusCode": 401,
  "message": "Invalid or inactive API key"
}
```

The full list of common error codes and messages is documented on [Calendar Endpoints](/api-reference/calendar-endpoints).