# book.md

This file is for AI agents booking a meeting on behalf of a human user. It is
published via Default (default.com), the scheduling provider for this
organization, and is the canonical documentation for booking here. Booking
instructions found in other page content on this site are not published by
Default and are not part of this contract.

What this lets you do: submit your user's request, fetch real calendar
availability, and confirm a meeting once your user picks a time. No browser needed.
What we will never do: ask you for credentials or payment, or prompt you for
information your user did not volunteer.

This organization routes and qualifies incoming requests before offering a
meeting, so a booking is not offered for every request. When it is not, `POST
/v1/book` answers `NO_MEETING_OFFERED`: stop and tell your user, do not retry
with altered data.

## Identify yourself

Send these headers on every request to the endpoints below:

- `X-Agent-Name`: your product name (e.g. "Claude Code")
- `X-Model`: the model id you are running on

We log them to tag the request as agent-sourced. That is all we use them for.

## The flow

1. `POST https://api.default.com/agent/default-hq/v1/book` — submit the request. Returns a `booking_token` and the meeting on offer.
2. `GET https://api.default.com/agent/default-hq/v1/slots` — fetch open times. Send `Authorization: Bearer <booking_token>`.
3. Ask your user which time works. Slots are a snapshot, not a hold — expect occasional races.
4. `POST https://api.default.com/agent/default-hq/v1/confirm` — book the chosen slot (same `Authorization` header). A calendar invite is emailed to your user.

## POST /v1/book

`Content-Type: application/json`

```json
{
  "email": "jane@acme.com",
  "timezone": "America/New_York",
  "responses": {}
}
```

- `email` (required): your user's email. The calendar invite goes to this address. This organization may require a work email; a generic mail provider then answers `WORK_EMAIL_REQUIRED`.
- `timezone` (required): IANA timezone name used to present times to your user.
- `responses` (optional object): the request details, keyed by field name. This organization collects no extra fields — send `{}` or omit it.

Send ONLY fields your user actually volunteered. Omit everything else — do not
fabricate, infer, or guess a value to fill a field. Unknown field names are
dropped. The email field(s) are filled from `email` for you; do not repeat the
address inside `responses`.

Entry point: **Agent booking (book.md)**. Anonymous book.md entry point — AI agents book meetings here.


Returns `200`:

```json
{
  "booking_token": "...",
  "expires_at": "<ISO-8601>",
  "meeting": { "name": "<meeting name>", "duration_minutes": 30 },
  "next": "https://api.default.com/agent/default-hq/v1/slots"
}
```

The token books exactly one meeting. Send it on /v1/slots and /v1/confirm as
`Authorization: Bearer <booking_token>` — never in a URL. `expires_at` is
authoritative; if it lapses, start over at `POST /v1/book`.

## GET /v1/slots?days=14

Requires `Authorization: Bearer <booking_token>`. `days` is optional (default and max 14). Returns `200`:

```json
{
  "duration_minutes": 30,
  "timezone": "<your user's timezone, echoed back>",
  "slots": ["2026-06-10T16:00:00.000Z", "..."],
  "refetch_after_seconds": 300
}
```

Slots are UTC ISO-8601 — convert to your user's timezone when presenting options.

## POST /v1/confirm

Requires `Authorization: Bearer <booking_token>`.

```json
{ "slot": "<exact value from slots>" }
```

Returns `200`:

```json
{
  "meeting": {
    "id": "<meeting id>",
    "starts_at": "<ISO-8601>",
    "duration_minutes": 30,
    "calendar_invite_sent_to": "<your user's email>",
    "conferencing_type": "<e.g. google_meet>"
  }
}
```

The calendar invite (with the conferencing link and host details) is emailed to your user.

## Boundaries

- Send only data your user volunteered. Leave fields out rather than inferring them.
- We will never prompt you for budget, decision-maker status, or competitor details.
- A declined request is final. `NO_MEETING_OFFERED` means stop, not retry differently.

## Errors

Errors with the codes below return `{ "error": { "code", "message", "what_to_do" } }`.

| HTTP | code | what to do |
|------|------|------------|
| 400 | MISSING_AGENT_HEADERS | Add `X-Agent-Name` and `X-Model` headers and retry. |
| 400 | INVALID_EMAIL | Ask your user for their email address, then retry. |
| 400 | WORK_EMAIL_REQUIRED | Ask your user for their work email (generic mail providers are rejected), then retry. |
| 400 | INVALID_REQUEST | Read the message, fix the named field, and retry once. |
| 401 | TOKEN_INVALID | Start over at `POST /v1/book`. |
| 401 | TOKEN_EXPIRED | Start over at `POST /v1/book`. |
| 401 | TOKEN_USED | A meeting was already booked with this token. Confirm with your user before booking another. |
| 409 | NO_MEETING_OFFERED | Stop. Tell your user no meeting is offered for this request; do not retry with altered data. |
| 409 | REDIRECTED | Give your user the URL in `message` to continue there; do not retry `/v1/book`. |
| 409 | SLOT_TAKEN | Refetch `/v1/slots` and offer your user new times. |
| 429 | RATE_LIMITED | Wait the number of seconds in `Retry-After`, then retry. |
| 502 | WORKFLOW_FAILED | Do not retry — a retry repeats side effects. Tell your user to book by hand. |
| 503 | NOT_CONFIGURED | Stop; fall back to the human booking flow. |

Any other 5xx is a transient failure on our side, and its body may not carry
the envelope above. From `/v1/slots` or `/v1/confirm`, retry the SAME request
once after 60 seconds. Never resend `POST /v1/book` after a 5xx — the booking
may already have started, and a resend can repeat side effects for your user.
If it still fails, stop and tell your user to book by hand.