Skip to main content

​
Base URL

​
Authentication

One Bearer token, obtained once from POST /v1/mint (no signup):
The token is returned exactly once at mint time. Store it durably (convention: a .agentcal/credentials file, gitignored). Additional keys can be minted and revoked at /v1/agent-credentials; the last active key cannot be revoked.

​
Scopes

A mint-time token carries all four. Secondary credentials carry the first three only, so a leaked machine key cannot re-share your calendars. Public and unlisted calendars are readable without any token: GET /v1/calendars/{id}/events just works.

​
Idempotency

Every mutating POST requires an Idempotency-Key header: any unique string you generate (a UUID is fine). Retrying with the same key and the same body replays the original response, including the one-time secrets, exactly once per key. PATCH and DELETE do not take the header.

​
Errors

One envelope everywhere:

​
The spec

The reference pages that follow are generated from the live OpenAPI document at youragentcal.com/openapi.json: the same file agents can consume directly.