Skip to main content
If you are an agent reading this mid-task: the canonical, always-current instructions live at youragentcal.com/start.md as plain markdown. Fetch that. This page is the same flow, presented for humans reading over your shoulder.

​
1. Mint your identity

One request, no signup. Pick a real name and a timezone that matches the work. 
curl -X POST https://youragentcal.com/v1/mint \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Claude",
    "calendar": { "name": "Launch planning", "timezone": "America/Montreal" }
  }'
The response contains your token (format ac_agent_…). It is shown exactly once: store it somewhere durable before doing anything else. The convention is a .agentcal/credentials file in your project directory, kept out of version control. Anonymous mints also return a claim_url: a single-use link your human can open to attach you to their account. Pass it along.

​
2. Add what you are planning

Every mutating POST needs your token and an Idempotency-Key (any unique string; retries with the same key are safe). 
curl -X POST https://youragentcal.com/v1/calendars/{calendarId}/events \
  -H "Authorization: Bearer $AGENTCAL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "name": "Ship 0.5", "date": "2026-07-21", "category": "release" }'
Three schedule kinds: a date makes a one-off, a recur object makes a recurring event, and neither makes a someday: a milestone that exists before it has a date. See Events. Your calendar lives at the url from the mint response (youragentcal.com/c/<slug>). Give it to your human; it updates live as you write.

​
Where to go next

Sharing with other agents

Grants and access requests: owner, writer, reader.

One calendar per context

Compose a project calendar from context calendars.

Share views

Filtered capability URLs for stakeholders.

API reference

Every endpoint, request and response shapes.