# Chronary

> Calendar-as-a-service API for AI agents. Manage calendars, schedule events, check availability, and sync external calendars.

Chronary provides a REST API and MCP server that let AI agents own and manage calendars, create events, query free/busy availability, subscribe to external iCal feeds, and receive real-time webhook notifications.

Base URL: `https://api.chronary.ai`
OpenAPI spec: `https://api.chronary.ai/openapi.json`
Authentication: `Authorization: Bearer chr_sk_...`

## Getting Started

- [Overview](https://docs.chronary.ai/getting-started/overview/): Key concepts — agents, calendars, events, availability
- [Quickstart](https://docs.chronary.ai/getting-started/quickstart/): Register your first agent and create a calendar in minutes
- [Authentication](https://docs.chronary.ai/getting-started/authentication/): API key setup

## API Reference

- [Agents](https://docs.chronary.ai/api-reference/agents/): CRUD for AI, human, and resource agents (`agt_` prefix IDs)
- [Calendars](https://docs.chronary.ai/api-reference/calendars/): Agent-owned and shared calendars (`cal_` prefix IDs), `agent_status` field (`idle`/`working`/`waiting`/`error`), `default_reminders` (reminder offsets events inherit), and `GET /v1/calendars/:id/context` for current/upcoming temporal context
- [Events](https://docs.chronary.ai/api-reference/events/): Calendar events with title, start/end time, status, and `reminders` (minutes before start; inherit calendar `default_reminders`, fall back to `[10]`) firing `event.reminder` webhooks + iCal VALARMs (`evt_` prefix IDs). **Pro plan:** temporal holds (`status: "hold"` with `hold_expires_at` + `PUT /v1/events/:id/confirm` / `/release`)
- [Availability](https://docs.chronary.ai/api-reference/availability/): Free/busy slot queries for single agents, calendars, or multiple agents; per-calendar `PUT/GET/DELETE /v1/calendars/:id/availability-rules` for buffer times and working hours. **Pro plan:** cross-agent availability (`GET /v1/availability?agents=agt_1,agt_2`)
- [Scheduling Proposals](https://docs.chronary.ai/api-reference/scheduling/): Multi-agent scheduling negotiation — create, respond, counter, resolve, and cancel proposals (`spr_` prefix IDs). **Pro plan only.**
- [Webhooks](https://docs.chronary.ai/api-reference/webhooks/): HMAC-signed webhook delivery for agent, event, and proposal lifecycle events (`whk_` prefix IDs) — 17 event types (incl. `event.reminder`). Use `GET /v1/webhooks/:id/deliveries` to inspect delivery history (`whd_` prefix IDs), filter by `status=failed|delivered|pending`, and include full payloads with `include_payload=true`. Response includes all-time `stats` (pending/delivered/failed counts) for at-a-glance success rate
- [iCal Subscriptions](https://docs.chronary.ai/api-reference/ical-subscriptions/): Subscribe calendars to external iCal feeds, polled approximately every 5 minutes (`ics_` prefix IDs)
- [iCal Feeds](https://docs.chronary.ai/api-reference/ical-feeds/): Consume any Chronary calendar as a standard iCal feed (no auth required)
- [API Keys](https://docs.chronary.ai/api-reference/keys/): Agent-scoped API keys (`chr_ak_*`) — `POST/GET/DELETE /v1/keys`. **Pro plan only.**
- [Usage](https://docs.chronary.ai/api-reference/usage/): Current-month usage counters and plan quota limits
- [Audit Log](https://docs.chronary.ai/api-reference/audit-log/): Org-level audit trail for mutating operations and auth events. Free: 3d retention; Pro: 90d; Custom: per-contract. Org-key only.
- [Plans](https://docs.chronary.ai/api-reference/plans/): Public plan catalog (`GET /v1/plans`) — pricing in minor units + ISO-4217, enforced limits, display features. Unauthenticated, cacheable; enterprise tier is `custom_pricing: true` with a `contact_url`
- [Agent Auth](https://docs.chronary.ai/api-reference/agent/): Self-signup for agents — `POST /v1/agent/sign-up` (unauthenticated; returns a restricted API key or an opaque dedup message) and `POST /v1/agent/verify` (six-digit OTP unlocks full write access). The restricted key only accepts GETs and the verify endpoint until OTP succeeds.
- [Feedback](https://docs.chronary.ai/api-reference/feedback/): `POST /v1/feedback` — submit `bug`/`feature`/`friction` reports with optional `context`. Rate-limited to 25 submissions per UTC day per org. Available on every plan. Fire-and-forget, returns `202 accepted`.
- [Account](https://docs.chronary.ai/api-reference/account/): `GET /v1/auth/export` (GDPR Art. 15+20 portability — JWT-only, returns full org data graph with decrypted webhook secrets / iCal URLs / event titles, rate-limited 10/hr/org) and `DELETE /v1/auth/account` (GDPR Art. 17 erasure — cascade-deletes org-owned rows, retains ToS acceptance audit per WA RCW 4.16.040). Both endpoints reject API keys; use the console UI or a delegated console JWT.
- [Terms of Service](https://docs.chronary.ai/api-reference/terms/): `GET /v1/auth/terms/current` (unauthenticated manifest lookup) and `PATCH /v1/auth/terms` (JWT-authed re-acceptance, appends immutable `tos_acceptances` audit row). Stale versions return `409 tos_version_stale` with `current_version`; the `Chronary-Terms-Upgrade-Required` response header flags stale orgs on authenticated REST + MCP traffic when the current version is material.

## MCP Server

- [MCP Overview](https://docs.chronary.ai/mcp/overview/): Use Chronary tools directly in Claude, Cursor, and other MCP hosts
- [Setup](https://docs.chronary.ai/mcp/setup/): Configure the MCP server endpoint
- [Tools Reference](https://docs.chronary.ai/mcp/tools-reference/): All 19 MCP tools — agents, calendars (incl. `get_calendar_context`), events, holds, availability (incl. rules: `set_availability_rules`/`get_availability_rules`/`clear_availability_rules`), scheduling proposals (`create_proposal`/`respond_to_proposal`/`resolve_proposal`/`cancel_proposal` — Pro plan), and iCal sync

## Guides

- [Calendars Guide](https://docs.chronary.ai/guides/calendars/): Agent-owned vs. shared calendars, timezone handling, `agent_status` patterns
- [Events Guide](https://docs.chronary.ai/guides/events/): Creating events, all-day events, event status lifecycle
- [Availability Guide](https://docs.chronary.ai/guides/availability/): Slot duration options, cross-agent intersection queries, availability rules
- [Webhooks Guide](https://docs.chronary.ai/guides/webhooks/): Verifying HMAC signatures, event payload shapes
- [iCal Subscriptions Guide](https://docs.chronary.ai/guides/ical-subscriptions/): Syncing Google Calendar, Outlook, and other iCal feeds
- [iCal Feeds Guide](https://docs.chronary.ai/guides/ical-feeds/): Subscribing calendar apps to a Chronary calendar feed
- [Calendar-Driven Agent Orchestration](https://docs.chronary.ai/guides/calendar-driven-agent-orchestration/): Use temporal context and `agent_status` to coordinate long-running agent workflows
- [Multi-Agent Scheduling Negotiation](https://docs.chronary.ai/guides/multi-agent-scheduling-negotiation/): End-to-end proposal/response/resolve flow for agent-to-agent coordination

## SDKs & Tooling

- OpenAPI 3.1 spec: `https://api.chronary.ai/openapi.json`
- TypeScript SDK: `npm install @chronary/sdk` — https://www.npmjs.com/package/@chronary/sdk
- Python SDK: `pip install chronary` — see [Python Quickstart](https://docs.chronary.ai/getting-started/python-quickstart/)
- Agent framework adapters: `npm install @chronary/toolkit` — https://www.npmjs.com/package/@chronary/toolkit (Vercel AI SDK, OpenAI Agents, LangChain, Mastra, MCP)
- Webhook + event schemas: `npm install @chronary/schemas` — https://www.npmjs.com/package/@chronary/schemas (Zod schemas for typed webhook payload validation)
- MCP stdio server (Claude Desktop / Cursor / VS Code / Windsurf): `npx -y @chronary/mcp` — https://www.npmjs.com/package/@chronary/mcp
- CLI: `npm install -g @chronary/cli` — see [CLI Quickstart](https://docs.chronary.ai/getting-started/cli-quickstart/)

## Resources

- [Error Codes](https://docs.chronary.ai/resources/errors/): Error types, HTTP status codes, request_id for tracing
- [Rate Limits & Quotas](https://docs.chronary.ai/resources/rate-limits/): 10 req/sec per key; monthly quotas by plan (free/pro/scale)
- [Plan Features & Capability Gating](https://docs.chronary.ai/resources/plans/): Pro plan unlocks scheduling negotiation, temporal holds, cross-agent availability, and agent-scoped API keys. Free-tier requests to Pro endpoints return `403 plan_required` with an `upgrade_url`. Every authenticated response includes `X-Chronary-Plan: free|pro|scale`.
- [Changelog](https://docs.chronary.ai/resources/changelog/): Recent API and platform changes