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

# Cal.com

> Connect a Cal.com account with an API key and let an agent book its event types

Check availabilityBookFindRescheduleCancelList

Cal.com is a scheduling system, so it already knows everything about how an appointment is made: the event type owns its length, its buffers, its minimum notice and the hours it is offered in, and Cal.com is the authority on whether a slot is free. Roark maps your agent's six actions onto it and stays out of the way.

Roark uses the **Cal.com v2 API**.

***

## What you need

| | |
| :- | :- |
| **Credential** | A Cal.com API key, beginning `cal_` (`cal_live_…` in production) |
| **Where it comes from** | Cal.com → **Settings → Developer → API keys** |
| **Scopes to select** | None to pick: Cal.com API keys are **not scoped**. The key carries the permissions of the account that created it |
| **Whose account** | The user that owns the event types the agent should book. Roark lists the event types belonging to that user |

> [!WARNING]
>
> Cal.com lets you give a key an expiry date. A key that expires takes your agent's booking with it, so either create it with no expiry or diary the rotation — and [rotate it in Roark](#rotating-the-key) before it lapses.

> [!NOTE]
>
> Paste an **API key**, not an OAuth access token from a Cal.com platform app. A token verifies once and then expires mid-call, which is why Roark checks for the `cal_` prefix and refuses anything else.

***

## Connect the account

**1. Create the API key in Cal.com**

In Cal.com, open **Settings → Developer → API keys**, create a key, and copy it. It is shown once.

**2. Add Cal.com to your agent**

In Roark, open your agent built on Roark, go to the **Tools** tab, and in the **Calendars** card choose **Add Cal.com**.

Give the account a name, pick the time zone the business keeps, and paste the key. **Verify and connect** checks it against Cal.com before anything is stored — an invalid key is refused on the spot and no connection is created.

![The Account step of the calendar setup dialog for Cal.com, with a name, a time zone and the API key field](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/connect-cal-com.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=54057dd1425407cd71fd2b81277e2521)

The account is connected once for the project. Every agent in the project can book on it.

**3. Pick the event types the agent may book**

Each appointment type points at one of the account's event types and carries a line telling the agent when it fits. Roark reads your event types live, so one added in Cal.com since you connected is already in the list.

![The Appointment types step for Cal.com, with the Checkup and New patient event types and a line describing when each fits](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/appointment-types.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=87752cb767c8a7782c401472821784fd)

The agent can reach the types you list here and nothing else on the account.

**4. Switch on the tools**

Cal.com supports all six actions. Switch on the ones the agent should be allowed to take — the three that write are marked **Changes data**.

![The Tools step with the six Cal.com actions and the Test bookings switch](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/tools.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=0f1c4dfb00344f1147db614da2e84334)

Prefer the API or the CLI?

```bash CLI theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark connections calendar create \
  --provider CAL_COM \
  --label "Front desk" \
  --api-key cal_live_... \
  --timezone America/Los_Angeles
```

```bash cURL theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -X POST https://api.roark.ai/v1/connections/calendar \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "CAL_COM",
    "label": "Front desk",
    "apiKey": "cal_live_...",
    "timezone": "America/Los_Angeles"
  }'
```

***

## What Cal.com decides, and what Roark does

| Decided by Cal.com | Handled by Roark |
| :- | :- |
| Appointment length, buffers, minimum notice, booking horizon | Which event types the agent may reach |
| Bookable hours and holidays | Offering times, and wording them for speech |
| Whether a slot is free, and refusing a double booking | Single-use slot ids, idempotent retries, the booking ledger |
| Whether a booking needs confirming | Telling the agent to say "requested", not "confirmed" |
| Confirmation and cancellation emails | What the agent says around the call |

### Event type details worth knowing

> [accordion] Event types that need confirmation
>
> An event type with a confirmation policy accepts the booking but does not confirm it. Roark returns `PENDING_CONFIRMATION`, and the sentence the agent reads says the time is *requested*. The setup dialog flags these event types while you configure them.

> [accordion] Hidden event types
>
> An event type hidden on your Cal.com booking page is still bookable through the API, which suits an overflow or after-hours slot the agent can offer but the public page does not.

> [accordion] Event types with several durations
>
> Where an event type offers a choice of lengths, pin one on the appointment type (`durationMinutes`). Leave it off and Cal.com uses the event type's own length.

> [accordion] The caller's email
>
> Cal.com needs an attendee email to book, so the agent asks the caller for one. An individual event type can declare further required booking fields of its own — Roark reads those when you configure the appointment type, so you find out at setup rather than mid-call.

> [accordion] Notes the caller asks to pass on
>
> Anything the caller asks to pass on is stored on the booking's metadata (`roarkNotes`), which is always present and reaches the booking's webhook and API — rather than a custom booking field whose slug differs per event type.

> [accordion] Booking references change on reschedule
>
> Cal.com issues a new reference when an appointment is moved. The reschedule tool returns the new one and the agent reads it back.

> [accordion] Cancellation reason
>
> A caller who gives no reason is recorded as *Cancelled by the caller*, which is what shows in Cal.com and in the cancellation email the attendee receives.

***

## Rotating the key

Paste a new key on the connection. It is verified before it is stored, and a verified key returns a connection in `INVALID_CREDENTIALS` to `ACTIVE`.

```bash CLI theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark connections calendar update <connection-id> --api-key cal_live_...
roark connections calendar check  <connection-id>
```

```bash cURL theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -X PATCH https://api.roark.ai/v1/connections/calendar/$CONNECTION_ID \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "cal_live_..." }'
```

***

## Troubleshooting

| What you see | What it means |
| :- | :- |
| `Must be a Cal.com API key (starts with "cal_")` | An OAuth access token or a v1 key was pasted. Create a key under **Settings → Developer → API keys** |
| The connection is created but no event types are listed | The key belongs to a different Cal.com user than the one that owns the event types |
| Status is `INVALID_CREDENTIALS` | The key was revoked or expired in Cal.com. [Rotate it](#rotating-the-key) |
| Disconnect refused with a `409` | A calendar tool is still bound to the connection; the refusal names the tools |

***

## Next steps

> [card] [Calendars overview](https://docs.roark.ai/documentation/integrations/calendars/overview.md)
>
> The six tools, slot ids, test bookings and limits

> [card] [Tools as code](https://docs.roark.ai/documentation/config-as-code/tools.md#calendar-handler)
>
> Declare the same setup in your config

> [card] [Build an agent](https://docs.roark.ai/documentation/config-as-code/build-an-agent.md)
>
> The agent that will do the booking

> [card] [Test tool calls](https://docs.roark.ai/documentation/recipes/tool-call-testing.md)
>
> Exercise booking paths in simulations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.