# Calendar API & MCP # Calendar API & MCP Everything you do in imatic Calendar, you can automate. Use the **REST API** to query slots and create bookings, **webhooks** to react to events in real time, and the **MCP server** to let an AI agent book on your behalf. This page is for developers wiring imatic Calendar into their own apps and tools. You manage credentials under **Developers** in your dashboard. :::note[Admin-managed] The **API keys** and **Webhooks** pages are managed by an **account admin**. If you don't see them in your dashboard, ask an admin on your account to issue a key or set up a webhook for you. ::: ## Authentication & API keys Calls to the API are authenticated with an **API key** sent as a bearer token: ```http Authorization: Bearer ``` Manage keys under **Developers → API keys**, where you can: - **Create** a key — copy the secret when it's shown; it isn't displayed again. - **List** your keys and see what each one is for. - **Revoke** a key instantly if it leaks or is no longer needed. - Assign **scopes** — each key carries only the permissions you grant, so a read-only key can list bookings but never create or cancel them. The available scopes are: | Scope | Grants | | --- | --- | | `slots:read` | Read available time slots for an event type | | `bookings:read` | List and read bookings | | `bookings:write` | Create, cancel, and reschedule bookings | | `mcp` | Use the MCP server (an umbrella that also covers `slots:read`, `bookings:read`, and `bookings:write`) | :::warning[Treat keys like passwords] A key grants access to your account within its scopes. Store it in a secret manager or environment variable, never in client-side code or a public repo. Revoke and rotate immediately if it's exposed. ::: ## REST API v1 The REST API is served under the `/v1` base path and returns JSON. The available resources are: - **Event types** — **list and read** your [event types](./event-types), plus **duplicate** an event type (`POST /v1/event-types/:code/duplicate`). (Create/edit/delete is done in the dashboard.) - **Slots** — query the available time slots for an event type (the same openings shown on your [booking page](./booking-page), with all buffers, notice, and caps applied). - **Bookings** — full CRUD plus **reschedule**: create a booking, list and read bookings, cancel, and move one to a new time. `GET /v1/bookings/stats` returns aggregate booking counts. - **Event links** — create, list, and revoke single-use booking links tied to an event type (`POST`/`GET /v1/event-types/:code/links`, `DELETE /v1/event-links/:linkCode`). - **Webhooks** — manage your webhook subscriptions programmatically. - **Users / me** — `GET /v1/users/me` returns the API key's identity (the authenticated account and org). - **Calendars** — work with your connected calendars (see [Integrations](./integrations)). A typical automation flow: query **slots** for an event type, then create a **booking** for the slot your user chose — the same atomic, no-double-book guarantee the [booking page](./booking-page#no-double-bookings-ever) uses applies to the API too. ## Webhooks Webhooks push events to your server the moment they happen, so you don't have to poll. Manage them under **Developers → Webhooks**. - **Subscribe** a URL to receive booking events. The events are exactly: `booking.created`, `booking.cancelled`, `booking.rescheduled`, and `booking.no_show`. - Each delivery is **signed with HMAC** — verify the signature header against your webhook's secret to confirm the request genuinely came from imatic Calendar before you trust the payload. - Use the built-in **Test** action to send a sample event to your endpoint while you're building, so you can confirm your handler works before going live. The signature travels in the `X-Imatic-Signature` header, in a Stripe-style format: ```http X-Imatic-Signature: t=,v1= ``` To verify: take `t` and the raw request body, compute `HMAC-SHA256(secret, ".")` (the timestamp and body joined by a literal dot), hex-encode it, and compare it to `v1`. Reject the request if they don't match. :::tip[Always verify the signature] Reject any webhook whose HMAC signature doesn't match. It's the difference between a trustworthy automation and an open door. ::: ## MCP server imatic Calendar ships a **Model Context Protocol (MCP) server**, so AI agents and assistants can read your availability and manage bookings through well-defined tools — using the same API-key authentication and scopes as the REST API. The server exposes **seven tools**: | Tool | What it does | | --- | --- | | `list_event_types` | List your bookable event types | | `list_slots` | Get open slots for an event type | | `create_booking` | Book a slot | | `cancel_booking` | Cancel a booking | | `reschedule_booking` | Move a booking to a new time | | `list_bookings` | List existing bookings | | `get_booking` | Read a single booking by its code | Point your MCP-capable client at the server, authenticate with an API key, and your agent can answer "when is Priya free Thursday?" and book the slot — all within the scopes you granted that key. The account's own profile is read over REST with `GET /v1/users/me`, not through an MCP tool. :::note[Scope your agent's key tightly] Give an AI agent a key with only the tools it needs. If it only needs to read availability, don't grant it cancel or reschedule permissions. ::: ## Next steps - [Integrations](./integrations) — connect Google and Outlook for two-way sync. - [Event types](./event-types) — the resource most of your API calls revolve around. - [Your public booking page](./booking-page) — the no-code path your automations mirror.