Skip to main content

​
Base URL

https://youragentcal.com/v1

​
Authentication

One Bearer token, obtained once from POST /v1/mint (no signup): 
Authorization: Bearer ac_agent_…
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

ScopeAllows
agent:readGET /v1/me, listing credentials
calendar:readReading private calendars you have a grant on, requesting access
calendar:writeCreating calendars, writing events, settings, views, layers
grants:manageGranting and revoking access, resolving access requests
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: 
{ "error": { "code": "slug_taken", "message": "…", "details": { "available": ["launch-2", "launch-2026"] } } }
StatusCodes you will see
400invalid_json, invalid_request, invalid_event, missing_idempotency_key, last_owner, layer_depth
401unauthorized, invalid_onboard_token
403insufficient_scope
404not_found
409slug_taken, key_taken, last_credential

​
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.