Build on Cals

Quick start

1. Open Dashboard → Developers. Owners and admins can create keys.
2. Name the key after your integration, choose its scopes and select Create key.
3. Copy the key straight away. Cals shows it once and stores only a hash.
4. Store it as a server-side secret and make your first request:

export CALS_API_KEY="cals_live_…"
curl https://cals.to/api/v1/event-types \
  -H "Authorization: Bearer $CALS_API_KEY"

{
  "data": [{ "id": "3f0c2a8e-6a3b-4d6e-9a43-0b1d2c3e4f50", "slug": "intro-call", "title": "Intro call", "duration": 30, "active": true }],
  "next_cursor": "eyJrIjoiMjAyNi0xMC0wN1QxMjowMDowMC4wMDBaIiwiaSI6IjNmMGMifQ"
}

Authentication

Every v1 request sends the key as a bearer token. The key identifies the workspace, so no request ever names one, and you can only ever see that workspace's data. Session cookies are ignored on these routes.

Each key carries scopes. A request outside them returns 403 insufficient_scope.

Keys look like cals_live_ followed by 32 letters and digits. The dashboard shows only the first characters, the creation date and when the key was last used. Revoking a key stops it on the very next request.

A workspace without a paid plan can hold 1 active key; paid plans can hold 10.

Endpoints

All endpoints live under /api/v1, accept and return JSON, and need the scope shown. Times are UTC ISO 8601.

curl https://cals.to/api/v1/event-types?limit=20 \
  -H "Authorization: Bearer $CALS_API_KEY"

curl -X POST https://cals.to/api/v1/event-types \
  -H "Authorization: Bearer $CALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Intro call","slug":"intro-call","duration":30,"location":"google_meet","active":true}'

curl -X PATCH https://cals.to/api/v1/event-types/3f0c2a8e-6a3b-4d6e-9a43-0b1d2c3e4f50 \
  -H "Authorization: Bearer $CALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"duration":45,"notice":240}'

curl "https://cals.to/api/v1/availability?event_type_id=3f0c2a8e-6a3b-4d6e-9a43-0b1d2c3e4f50&from=2026-11-02T00:00:00Z&to=2026-11-06T00:00:00Z&timezone=Europe/London" \
  -H "Authorization: Bearer $CALS_API_KEY"

curl "https://cals.to/api/v1/bookings?status=confirmed&from=2026-11-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $CALS_API_KEY"

curl https://cals.to/api/v1/bookings/9b2e7c1d-4f5a-4c3b-8d2e-1a0b9c8d7e6f \
  -H "Authorization: Bearer $CALS_API_KEY"

curl -X POST https://cals.to/api/v1/bookings \
  -H "Authorization: Bearer $CALS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"event_type_id":"3f0c2a8e-6a3b-4d6e-9a43-0b1d2c3e4f50","start":"2026-11-03T14:00:00Z","name":"Ada Lovelace","email":"ada@example.com","timezone":"Europe/London"}'

curl -X POST https://cals.to/api/v1/bookings/9b2e7c1d-4f5a-4c3b-8d2e-1a0b9c8d7e6f/cancel \
  -H "Authorization: Bearer $CALS_API_KEY"

curl -X POST https://cals.to/api/v1/bookings/9b2e7c1d-4f5a-4c3b-8d2e-1a0b9c8d7e6f/reschedule \
  -H "Authorization: Bearer $CALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start":"2026-11-04T09:30:00Z"}'

MCP setup

The Cals MCP server speaks Streamable HTTP. Without a key it offers the public guest-booking tools. With a key it adds host tools for your workspace, limited to the key's scopes; a request with an invalid key is refused rather than downgraded.

Claude Desktop

Add this to claude_desktop_config.json (Settings → Developer → Edit config). mcp-remote forwards the Authorization header; restart Claude afterwards.

{
  "mcpServers": {
    "cals": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://cals.to/api/public/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer cals_live_…"
      }
    }
  }
}

Claude Code

claude mcp add --transport http cals https://cals.to/api/public/mcp \
  --header "Authorization: Bearer $CALS_API_KEY"

Cursor

Add this to ~/.cursor/mcp.json, or .cursor/mcp.json in a project you do not commit secrets from.

{
  "mcpServers": {
    "cals": {
      "url": "https://cals.to/api/public/mcp",
      "headers": {
        "Authorization": "Bearer cals_live_…"
      }
    }
  }
}

ChatGPT and the OpenAI API

ChatGPT custom connectors support OAuth or no authentication, so in ChatGPT itself use the public guest tools at the same URL. For host tools, attach the server to the Responses API with this tool definition:

{
  "type": "mcp",
  "server_label": "cals",
  "server_url": "https://cals.to/api/public/mcp",
  "headers": {
    "Authorization": "Bearer cals_live_…"
  },
  "require_approval": "always"
}

Host tools

Rate limits

Each key may make 120 requests per minute. Each IP may fail authentication 20 times per minute; after that, even valid keys from that IP wait for the next minute. The MCP endpoint also allows 120 requests per minute per IP. Over a limit you get 429 rate_limited with a Retry-After header in seconds.

Plan allowances apply exactly as in the dashboard: monthly booking limits, Pro-only booking questions and Teams-only round-robin and collective meetings.

Errors

Errors use one envelope with a stable machine-readable code and a human message. Branch on the code, never on the message.

{
  "error": { "code": "insufficient_scope", "message": "This key needs the bookings:write scope." }
}

Pagination

List endpoints return { data, next_cursor }. Pass limit (1–100, default 50) and, for the next page, cursor set to the previous next_cursor. next_cursor is null on the last page. Cursors are opaque; keep your filters the same between pages.

curl "https://cals.to/api/v1/bookings?limit=100&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $CALS_API_KEY"

Idempotency

POST /bookings requires an Idempotency-Key header. Generate a new one (a UUID works) for each booking you intend to make and resend the same key when retrying a timeout. A repeat with the same key and body returns the original booking with Idempotent-Replayed: true; the same key with a different body returns 409. Keys are remembered for 24 hours and scoped to your workspace. Reschedule accepts the header too; without it, moving the same booking to the same time is treated as one request.

Webhooks

To react to bookings instead of polling, add a signed webhook in Dashboard → Agent workspace → Webhooks. Cals sends booking.confirmed, booking.cancelled and booking.failed, signed with HMAC-SHA256 in X-Cals-Signature, with at-least-once delivery and retries.

This page is also available as Markdown for agents and tools.