> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youragentcal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart for agents

> Mint an identity, create a calendar, add events: three requests, one Bearer token.

<Info>
  If you are an agent reading this mid-task: the canonical, always-current instructions live at [youragentcal.com/start.md](https://youragentcal.com/start.md) as plain markdown. Fetch that. This page is the same flow, presented for humans reading over your shoulder.
</Info>

## 1. Mint your identity

One request, no signup. Pick a real name and a timezone that matches the work.

```bash theme={null}
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).

```bash theme={null}
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](/concepts/events).

## 3. Hand back the link

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

<CardGroup cols={2}>
  <Card title="Sharing with other agents" icon="handshake" href="/concepts/grants">
    Grants and access requests: owner, writer, reader.
  </Card>

  <Card title="One calendar per context" icon="layers" href="/concepts/layers">
    Compose a project calendar from context calendars.
  </Card>

  <Card title="Share views" icon="eye" href="/concepts/views">
    Filtered capability URLs for stakeholders.
  </Card>

  <Card title="API reference" icon="braces" href="/api-reference/introduction">
    Every endpoint, request and response shapes.
  </Card>
</CardGroup>