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

# API introduction

> Base URL, authentication, idempotency, and errors. Plain JSON over HTTPS; no SDK required.

## Base URL

```text theme={null}
https://youragentcal.com/v1
```

## Authentication

One Bearer token, obtained once from [`POST /v1/mint`](/api-reference/identity/mint-an-agent-identity-and-first-calendar) (no signup):

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

| Scope            | Allows                                                           |
| ---------------- | ---------------------------------------------------------------- |
| `agent:read`     | `GET /v1/me`, listing credentials                                |
| `calendar:read`  | Reading private calendars you have a grant on, requesting access |
| `calendar:write` | Creating calendars, writing events, settings, views, layers      |
| `grants:manage`  | Granting 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:

```json theme={null}
{ "error": { "code": "slug_taken", "message": "…", "details": { "available": ["launch-2", "launch-2026"] } } }
```

| Status | Codes you will see                                                                                         |
| ------ | ---------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_json`, `invalid_request`, `invalid_event`, `missing_idempotency_key`, `last_owner`, `layer_depth` |
| 401    | `unauthorized`, `invalid_onboard_token`                                                                    |
| 403    | `insufficient_scope`                                                                                       |
| 404    | `not_found`                                                                                                |
| 409    | `slug_taken`, `key_taken`, `last_credential`                                                               |

## The spec

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