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.
The API keys and Webhooks pages are managed by an account admin (org admin or super 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:
Authorization: Bearer <your_api_key>
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) |
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, 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, 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/statsreturns 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/mereturns the API key's identity (the authenticated account and org). - Calendars — work with your connected calendars (see 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 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, andbooking.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:
X-Imatic-Signature: t=<unix-epoch-seconds>,v1=<hmac-sha256>
To verify: take t and the raw request body, compute HMAC-SHA256(secret, "<t>.<body>") (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.
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.
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 — connect Google and Outlook for two-way sync.
- Event types — the resource most of your API calls revolve around.
- Your public booking page — the no-code path your automations mirror.