Platform API
The Platform API is a public, server-to-server REST API for building integrations on top of Cirrus Insight. It's designed for customer engineering teams and partners — most immediately, for AI agents that schedule meetings on behalf of end-users without requiring the Cirrus Insight hosted UI.
Base URL
https://altus.cirrusinsight.com/api/v1alpha1Authentication
Every request must include an API key issued by your organization's developer dashboard, in the X-Cirrus-Api-Key header:
Tokens are 56 characters total — a fixed ci_live_ prefix plus 48 URL-safe random characters. Treat the whole string as a secret.
See Authentication for how to create, scope, expire, and revoke tokens.
X-Cirrus-Api-Key: ci_live_<...>Quickstart
The shortest path from "have a token" to "booked a meeting":
TOKEN=ci_live_<...>
BASE=https://altus.cirrusinsight.com/api/v1alpha1
# 1. List the smart schedules your org has configured
curl -s "$BASE/smart-schedules" \
-H "X-Cirrus-Api-Key: $TOKEN"
# 2. Fetch one schedule's definition + form schema
curl -s "$BASE/smart-schedules/sched_<...>" \
-H "X-Cirrus-Api-Key: $TOKEN"
# 3. Submit form values and get matched host + slot pairs
curl -s "$BASE/smart-schedules/sched_<...>/availability" \
-H "X-Cirrus-Api-Key: $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"formValues": { "region": "NA-East" },
"dateRange": {
"start": "2026-06-15T00:00:00Z",
"end": "2026-06-29T00:00:00Z"
}
}'
# 4. Book a meeting using one of the returned slot tokens
curl -s "$BASE/scheduled-meetings" \
-H "X-Cirrus-Api-Key: $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"slotToken": "eyJzY2hlZHVsZUlkIjoic2NoZWRf...",
"attendee": {
"firstName": "Sample",
"lastName": "Guest",
"email": "guest@example.com",
"phone": "+14155551234"
},
"formValues": { "region": "NA-East" }
}'Conventions
- REST style. Resources are nouns (
/smart-schedules,/scheduled-meetings). Standard verbs (GET,POST,PATCH,DELETE) map to the operations they suggest. - JSON only. Requests and responses use
application/json. Errors useapplication/problem+jsonper RFC 7807. - Cursor pagination on all list endpoints. See Pagination below.
- Sorting on list endpoints uses the JSON:API convention (
?sort=fieldascending,?sort=-fielddescending). Each endpoint publishes its own allowlist; anything outside it returns400 invalid-sort-field. - Idempotency is supported on
POST /scheduled-meetingsandPATCH /scheduled-meetings/{id}via theIdempotency-Keyheader. See Idempotency below. - IDs are opaque, prefixed strings. Smart schedules are
sched_..., scheduled meetings aremtg_..., hosts areusr_..., webhook subscriptions aresub_..., webhook delivery attempts arewd_.... Slot tokens returned from/availabilityare opaque, signed strings with no fixed prefix — see Slot. - Times are ISO 8601 UTC unless explicitly stated otherwise (a Smart Schedule definition carries a
timeZonefield that anchors business-hours logic on the server; every timestamp in a response is in UTC).
Pagination
List endpoints accept cursor, limit, and sort query parameters:
Responses include nextCursor, which is null on the last page. Pass the value back unchanged to fetch the next page. limit defaults to 25 and is clamped to the range 1–100 — a caller sending limit=500 receives 100 rows without an error, and limit=0 receives 1. A non-numeric limit is a 400.
Cursors carry the sort field and direction they were minted under. Replaying a cursor against a different sort is a 400 invalid-cursor rather than a silent re-page — this prevents skipping or repeating rows across the keyset boundary.
GET /smart-schedules?limit=50&sort=-updatedAt&cursor=eyJmaWVsZCI6InVwZGF0ZWRBdCIs...Idempotency
For booking and reschedule requests, supply an Idempotency-Key header containing a client-generated UUID (or any opaque, unique string up to 255 chars):
Repeating a request with the same key within 24 hours returns the original response (with an X-Idempotent-Replay: true header) without re-executing the operation. Different keys, or the same key after 24 hours, are treated as new requests. Idempotency keys are scoped per token.
A repeated key with a different request body returns 422 idempotency-key-conflict — this catches accidental key reuse across semantically-different requests.
This protects against double-bookings when retrying a request after a network timeout, and lets AI agents safely retry without complex out-of-band deduplication.
Idempotency-Key: 8c1b0a90-3e2d-4f7d-8a4f-92c7c5e8aa01Rate Limits
Limits are enforced at the gateway, per token, per one-minute rolling window unless otherwise stated:
| Operation tier | Limit |
|---|---|
Read endpoints (GET /smart-schedules, GET /scheduled-meetings/{id}, list endpoints, GET /webhook-subscriptions, etc.) | 300 / minute |
Availability (POST /smart-schedules/{id}/availability) | 60 / minute |
Write endpoints (POST /scheduled-meetings, PATCH, DELETE, webhook-subscription writes) | 20 / minute |
| Per-token daily quota (all operations combined) | 50,000 / day |
Buckets are independent — spending your read budget doesn't affect your write budget. Limits exceeded return 429 Too Many Requests with a Retry-After header indicating the number of seconds until the next allowed request. Enterprise plans negotiate custom rate limits — talk to your account team.
Errors
Errors return RFC 7807 problem-details:
See Errors for the full catalog and how to handle each one.
{
"type": "https://docs.cirrusinsight.com/platform-api/errors/slot-conflict",
"title": "Slot is no longer available",
"status": 409,
"detail": "The selected slot conflicts with the host's calendar.",
"rerunAvailability": true
}