API reference
ChronaPilot exposes a single REST surface, versioned and JSON-only. Every endpoint described below is reachable on the live and sandbox base URLs.
- Live: https://api.chronapilot.com
- Sandbox: https://api-sandbox.chronapilot.com
All requests must include:
- Authorization: Bearer
or Authorization: Bearer - Chronapilot-Version: 2026-05-20
Resources
Each resource has its own reference page. Most have full CRUD plus a handful of operations.
Connections
Manage OAuth links to Google, Microsoft, and iCloud calendars.
Calendars
Enumerate and configure individual calendars within a connection.
Events
Create, read, update, cancel calendar events. The core CRUD.
Free/Busy
Bulk availability lookup and slot-finder.
Departure
Traffic and weather-aware optimal-leave-time calculation.
ETA Tracking
Live event-day arrival tracking and prediction.
Event Health
Confidence score and risk surface per event.
Conflict Detection
Find conflicts before booking.
Smart Suggestions
Multi-constraint slot finder, natural-language or structured.
Voice Realtime
Streaming voice assistant pre-bound to a calendar.
NL Scheduling
Natural-language → structured event parser.
Push Notifications
Device registration and smart, travel-time-adjusted pushes.
Reminders
Schedule and manage event reminders.
Invitations
Send and track ICS-based attendee invitations.
Users
ChronaPilot Connect managed end-users.
Webhook Endpoints
Register, manage, and replay webhook deliveries.
Common headers
| Header | When | Description |
|---|---|---|
| Authorization | Always | Bearer |
| Chronapilot-Version | Always | Date-based API version, e.g. 2026-05-20. See Versioning. |
| Chronapilot-Account | Connect only | cpa_… — act on behalf of a connected account when calling with a platform sk_live_ key. See Connect. |
| Idempotency-Key | Recommended on POST/PATCH | Client-generated UUID. Retries within 24h return the original response. See Idempotency. |
| Content-Type | On request bodies | application/json. |
Scoping rules
Every API call has an implicit scope determining whose data it can read or write.
- Single-tenant — calling with sk_live_… (or sk_test_…) acts on your platform's own ChronaPilot account. Calls that take a user_id parameter (events, reminders, notifications) require it explicitly; absent that, the call applies to the account-owner user.
- OAuth (Connect access token) — calling with Bearer cat_… acts on the connected account encoded in the token. user_id is optional and, when present, must match.
- Connect via header — calling with Bearer sk_live_… plus Chronapilot-Account: cpa_… acts on that connected account. The header is required for any operation against a Connect end-user.
A call that doesn't satisfy the scoping rules returns 403 authorization_failed.
Resource ID prefixes
| Prefix | Resource |
|---|---|
| evt_ | Event |
| con_ | Provider connection (Google / Microsoft / iCloud) |
| cal_ | Calendar |
| usr_ | User |
| wbk_ | Webhook endpoint |
| whe_ | Webhook event (delivery envelope) |
| rem_ | Reminder |
| inv_ | Invitation |
| not_ | Notification |
| dev_ | Device (FCM/APNS token) |
| hub_ | Voice session |
| cpa_ | Connect account |
| cli_ | Connect OAuth client (registered platform) |
| cat_ | Connect access token |
| crt_ | Connect refresh token |
| req_ | Request ID (in responses; trace key) |
Common parameters
| Parameter | Description |
|---|---|
| expand[] | Expand nested objects (expand[]=connection, expand[]=monitoring). |
| fields | Sparse fields — comma-separated list of properties to return. |
| limit | List-endpoint page size. Max 100. |
| starting_after | Cursor for forward pagination. |
| ending_before | Cursor for backward pagination. |