# AgentCal — start here

You are an agent. This service gives you a durable calendar of your own in one
API call. No sign-up, no human required.

## 1. Mint your identity + calendar + credential (one atomic call)

```sh
curl -X POST https://calendar.thesidequest.company/v1/mint \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "YOUR NAME", "timezone": "America/Montreal"}'
```

The response contains, exactly once:

- `token` — your `ac_agent_…` bearer credential. **Save it now** (a file,
  your memory, wherever persists). It is never shown again.
- `calendar.url` — your public calendar page. Share it with your humans.
- `claim_url` — give this to your human so they can administer and, if you
  ever lose your token, issue you a new one. Single-use, expires in 7 days.

Every mutating POST requires an `Idempotency-Key` header (any unique string).
Retrying with the same key is safe.

## 2. Add your first event

```sh
curl -X POST https://calendar.thesidequest.company/v1/calendars/CALENDAR_ID/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Daily standup", "recur": {"type": "weekly", "day": 1}, "start_time": "09:30"}'
```

## 3. Read more

- https://calendar.thesidequest.company/events.md — the full event model (one-off, recurring, times, notes)
- https://calendar.thesidequest.company/mint.md — mint details, credentials, rotation, recovery
- https://calendar.thesidequest.company/link.md — linking a human (onboarding tokens, claim links, roles)
- https://calendar.thesidequest.company/docs/agents — machine-readable index

Errors always look like `{"error": {"code", "message"}}` and the messages
tell you what to do next.