# bookameet.ing HTTP API

Base URL: https://bookameet.ing. The routes below need no account, no API key and no special header. Bodies are JSON. Every time is an ISO 8601 instant; send it with `Z` or an offset (`2026-12-03T10:00:00Z`, `2026-12-03T11:00:00+01:00`); a time without one is refused. Answers give times in UTC.

To book a meeting:

1. `GET /api/v1/links/{handle}/{slug}/times` for the open slots (`GET /api/v1/links/{handle}` lists a host’s links).
2. `POST /api/v1/bookings` with one slot’s `start` and the invitee. Answer the link’s required `questions` in `answers`.
3. Keep `manageUrl` (or `manageToken`): it is the only way to view, reschedule or cancel the booking.

## GET /api/v1/links/{handle}

A host’s public page: their public event types (links).

- `handle` (path, string, required)

Answers 200: `{ handle, hostName, eventTypes: [{ handle, hostName, slug, title, description, durations: number[] (minutes), timeZone, questions: [{ id, label, required, type, options? }] }] }`

```sh
curl "https://bookameet.ing/api/v1/links/ada"
```

## GET /api/v1/links/{handle}/{slug}

One link: its title, durations, time zone and the questions a booking must answer.

- `handle` (path, string, required)
- `slug` (path, string, required)

Answers 200: `{ handle, hostName, slug, title, description, durations: number[] (minutes), timeZone, questions: [{ id, label, required, type, options? }] }`

```sh
curl "https://bookameet.ing/api/v1/links/ada/intro"
```

## GET /api/v1/links/{handle}/{slug}/times

The bookable times of one link. Book one of the returned slots’ `start`.

- `handle` (path, string, required)
- `slug` (path, string, required)
- `from` (query, ISO 8601 instant, optional): start of the range; defaults to now
- `to` (query, ISO 8601 instant, optional): end of the range; defaults to from + 14 days, at most 62 days after from
- `duration` (query, integer, optional): minutes; one of the link’s durations, defaults to the first

Answers 200: `{ link: { handle, hostName, slug, title, description, durations: number[] (minutes), timeZone, questions: [{ id, label, required, type, options? }] }, durationMinutes, slots: [{ start, end }], generatedAt, available: boolean, unavailableReason?: 'calendar_disconnected', bookableUntil: string | null }`

```sh
curl "https://bookameet.ing/api/v1/links/ada/intro/times?duration=30"
```

## POST /api/v1/bookings

Books a time. Answers 201 with the booking; keep its `manageUrl` to reschedule or cancel.

- `handle` (JSON body, string, required)
- `slug` (JSON body, string, required)
- `start` (JSON body, ISO 8601 instant, required): a slot’s start from the times route
- `durationMinutes` (JSON body, integer, optional): defaults to the link’s first duration
- `invitee` (JSON body, object, required)
- `invitee.name` (JSON body, string, required): the invitee’s name
- `invitee.email` (JSON body, string, required): the invitee’s email; the confirmation goes there
- `invitee.timeZone` (JSON body, string, required): IANA time zone, e.g. America/New_York
- `guests` (JSON body, string[], optional): up to 10 more attendee emails
- `answers` (JSON body, object of string or string[], optional): question id to answer; every required question must be answered
- `oneOffLinkId` (JSON body, string, optional): when booking a one-off link: its id

Answers 201: `{ id, status, start, end, eventTitle, hostName, invitee: { name, email, timeZone }, guests: string[], meetUrl: string | null, manageToken, manageUrl, link: { handle, slug, timeZone } }`

```sh
curl -X POST "https://bookameet.ing/api/v1/bookings" \
  -H 'Content-Type: application/json' \
  -d '{"handle":"ada","slug":"intro","start":"2026-12-03T10:00:00Z","invitee":{"name":"Grace Hopper","email":"grace@example.com","timeZone":"America/New_York"}}'
```

## GET /api/v1/bookings/{manageToken}

A booking, by the token in its manage URL.

- `manageToken` (path, string, required)

Answers 200: `{ id, status, start, end, eventTitle, hostName, invitee: { name, email, timeZone }, guests: string[], meetUrl: string | null, manageToken, manageUrl, link: { handle, slug, timeZone } }`

```sh
curl "https://bookameet.ing/api/v1/bookings/MANAGE_TOKEN"
```

## POST /api/v1/bookings/{manageToken}/reschedule

Moves a booking to a new start, keeping its length. Pick the start from the times route.

- `manageToken` (path, string, required)
- `start` (JSON body, ISO 8601 instant, required): the new start

Answers 200: `{ id, status, start, end, eventTitle, hostName, invitee: { name, email, timeZone }, guests: string[], meetUrl: string | null, manageToken, manageUrl, link: { handle, slug, timeZone } }`

```sh
curl -X POST "https://bookameet.ing/api/v1/bookings/MANAGE_TOKEN/reschedule" \
  -H 'Content-Type: application/json' \
  -d '{"start":"2026-12-04T10:00:00Z"}'
```

## POST /api/v1/bookings/{manageToken}/cancel

Cancels a booking. The body may be empty.

- `manageToken` (path, string, required)
- `reason` (JSON body, string, optional): told to both sides

Answers 200: `{ id, status, start, end, eventTitle, hostName, invitee: { name, email, timeZone }, guests: string[], meetUrl: string | null, manageToken, manageUrl, link: { handle, slug, timeZone } }`

```sh
curl -X POST "https://bookameet.ing/api/v1/bookings/MANAGE_TOKEN/cancel" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Something came up"}'
```

## GET /api/v1/one-off/{id}

A one-off link (the id in a /o/{id} URL) and the times it still offers. Book one with POST /api/v1/bookings, giving `link.handle`, `link.slug` and `oneOffLinkId`.

- `id` (path, string, required)

Answers 200: `{ link: { handle, hostName, slug, title, description, durations: number[] (minutes), timeZone, questions: [{ id, label, required, type, options? }] }, durationMinutes, slots: [{ start, end }], state: 'open' | 'used' | 'expired', generatedAt, available: boolean, unavailableReason?: 'calendar_disconnected' }`

```sh
curl "https://bookameet.ing/api/v1/one-off/ONE_OFF_ID"
```

## Errors

A failure answers with a JSON body `{ "error": { "code", "message", "detail"?, "issues"? } }`. Branch on `code`; `message` says what was wrong (for `invalid_input`, which field). An `invalid_input` about particular fields also lists them in `issues`, each `{ "path", "problem", "message", "limit"?, "of"?, "inclusive"? }` with `problem` one of `required`, `too_small`, `too_big`, `not_whole`, `invalid`.

| code | status |
|-|-|
| `invalid_input` | 400 |
| `unauthorized` | 401 |
| `not_found` | 404 |
| `slot_unavailable` | 409 |
| `calendar_disconnected` | 409 |
| `conflict` | 409 |
| `provider_error` | 502 |
| `method_not_allowed` | 405 (the `Allow` header lists the methods the path takes) |

A body field the route does not list is refused with `invalid_input` naming it, never ignored.

When the time asked for is taken or no longer on offer, `POST /api/v1/bookings` (and reschedule) answers 409 with `code: "slot_unavailable"` and up to 5 other open times in `detail.alternatives`, as `[{ "start", "end" }]`. Book one of those instead:

```json
{ "error": { "code": "slot_unavailable", "message": "…", "detail": { "alternatives": [{ "start": "2026-12-03T10:30:00.000Z", "end": "2026-12-03T11:00:00.000Z" }] } } }
```
