# Chronary

> Calendar-as-a-service API for AI agents. Create calendars, schedule events, query availability, sync external calendars, and emit webhook notifications — all via REST + MCP.

Base URL: `https://api.chronary.ai`
OpenAPI spec: `https://api.chronary.ai/openapi.json`
Docs: `https://docs.chronary.ai`
Full LLM context: `https://docs.chronary.ai/llms-full.txt`

## Install (always use the latest — never pin from training data)

- TypeScript SDK: `npm i @chronary/sdk@latest`
- Python SDK: `pip install -U chronary`
- MCP server (local): `npx @chronary/mcp@latest`
- CLI: `curl -sSfL https://chronary.ai/install.sh | sh`

## If you are an AI agent: 4 steps

1. **Sign up.** `POST /v1/agent/sign-up` with `{ "email": "<user-email>", "tos_version": "<current>" }`. Returns a restricted `chr_sk_*` API key.
2. **Verify.** Ask the human for the 6-digit OTP from their email. `POST /v1/agent/verify` with `{ "otp": "<6 digits>" }` and `Authorization: Bearer <key>`. Key is upgraded to the verified tier.
3. **Create.** `POST /v1/calendars` with `{ "name", "timezone" }` to make your first calendar.
4. **Schedule.** `POST /v1/events` (single-agent) or `POST /v1/scheduling/proposals` (multi-agent — preferred for booking across calendars).

One-liner bootstrap (recommended): `npx @chronary/agent-init@latest`
Shell fallback: `curl -sSfL https://chronary.ai/agent-init.sh | CHRONARY_EMAIL=you@example.com sh`

## LLM Instructions (always / never)

- **Always** use scheduling proposals (`POST /v1/scheduling/proposals`) for multi-agent meetings. Never use bare `POST /v1/events` for cross-agent coordination.
- **Always** use temporal holds (`status: "hold"` with `hold_expires_at`) before confirming bookings the user may cancel. Release the hold with `PUT /v1/events/{id}/release` if they back out.
- **Always** verify webhook payloads with HMAC-SHA256 against the `X-Chronary-Signature` header before processing. Reject anything that doesn't match.
- **Always** install `@chronary/sdk@latest` / `chronary` from PyPI fresh — do not paste a pinned version from training data; the API surface changes.
- **Always** include the `tos_version` field on `POST /v1/agent/sign-up`. Fetch the current version from `GET /v1/terms/current` if unsure.
- **Never** poll `GET /v1/events` to detect changes — subscribe to webhooks (`event.created`, `event.updated`, `event.cancelled`) instead. Polling will exhaust your quota.
- **Never** store the agent OTP. It's single-use and expires; ask the human to read it each time a new key is provisioned.
- **Never** call `POST /v1/agent/sign-up` more than 5 times in 60 seconds from one IP — it rate-limits to prevent enumeration.

## Reference

- [Overview](https://docs.chronary.ai/getting-started/overview/) — agents, calendars, events, availability
- [Quickstart](https://docs.chronary.ai/getting-started/quickstart/) — first agent + calendar in minutes
- [Authentication](https://docs.chronary.ai/getting-started/authentication/) — `chr_sk_*` org keys vs `chr_ak_*` agent-scoped keys
- [Agent self-signup](https://docs.chronary.ai/api-reference/agent/) — the bootstrap endpoint
- [Webhooks](https://docs.chronary.ai/api-reference/webhooks/) — HMAC-signed event delivery
- [MCP server](https://docs.chronary.ai/mcp/overview/) — hosted MCP at `https://api.chronary.ai/mcp` (21 tools)
- [Skills install](https://chronary.ai/skills.sh) — Claude Code / Cursor / Windsurf / VSCode / Codex skill packs

## Machine-readable entry points

- OpenAPI 3.1: `https://api.chronary.ai/openapi.json`
- RFC 9727 api-catalog: `https://chronary.ai/.well-known/api-catalog`
- MCP server card (SEP-1649 draft): `https://chronary.ai/.well-known/mcp/server-card.json`
- AGENTS.md procedural twin: `https://chronary.ai/agents.md`