> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/booking-links/openapi.json](/docs/api/booking-links/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Booking links

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

Links people use to book a meeting type.

Meetings and calls. 4 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/booking-links/openapi.json](/docs/api/booking-links/openapi.json).

- `GET /v1/booking-links` - List your open single-use links (`booking-links.list`): [/docs/api/booking-links/list.md](/docs/api/booking-links/list.md)
- `POST /v1/booking-links` - Create a booking link (`booking-links.create`): [/docs/api/booking-links/create.md](/docs/api/booking-links/create.md)
- `PATCH /v1/booking-links/{bookingLinkId}` - Update a single-use link's times (`booking-links.update`): [/docs/api/booking-links/update.md](/docs/api/booking-links/update.md)
- `GET /v1/booking-links/suggested-times` - Get suggested times for a person (`booking-links.suggested-times`): [/docs/api/booking-links/suggested-times.md](/docs/api/booking-links/suggested-times.md)

## List your open single-use links

`GET /v1/booking-links` - operationId `booking-links.list`

| Permission | Rate limit |
| --- | --- |
| Calendar view | 12,000 requests a minute per API key |

Lists the single-use links you made in this workspace that can still book: not used, not expired, and on a
meeting type that still exists. Newest first. A single-use link belongs to the member who made it, so you see only
your own, also with the `members` permission.

The items have no `url`: Kenso keeps only a hash of each link's token, so the URL is shown once, when you
create the link. Page with `limit`, from 1 to 200 (default 50), and the `cursor` from
`pagination.nextCursor`.

Errors:

- `400 validation_failed`: `limit` is out of range, or `cursor` is not valid.
- `403 forbidden`: the API key is not tied to a member of the workspace.

Requires Meetings view.

Needs the `scheduler` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/booking-links/GET/v1/booking-links)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer (int32) | no | Number of links per page, from 1 to 200. Default 50. |
| `cursor` | query | string | no | The `nextCursor` from the previous page. Omit it for the first page. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a list of `BookingLinkSummary`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The link's id. |
| `kind` | string | The kind of link: always `single_use`. |
| `meetingTypeId` | integer (int64) | The meeting type the link books. |
| `personId` | integer (int64) | The person the link was made for; null when none was named. |
| `createdAt` | string (date-time) | When the link was made (UTC). |
| `expiresAt` | string (date-time) | When the link expires (UTC). |
| `availability` | AvailabilitySchedule | The link's own available times; null when it uses the meeting type's. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/booking-links?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": 812,
      "kind": "string",
      "meetingTypeId": 812,
      "personId": 812,
      "createdAt": "2026-09-23T15:02:11Z",
      "expiresAt": "2026-09-23T15:02:11Z",
      "availability": {
        "timeZone": "America/New_York",
        "weekly": {
          "monday": [
            {}
          ],
          "tuesday": [
            {}
          ],
          "wednesday": [
            {}
          ],
          "thursday": [
            {}
          ],
          "friday": [
            {}
          ],
          "saturday": [
            {}
          ],
          "sunday": [
            {}
          ]
        },
        "overrides": [
          {
            "date": "string",
            "ranges": []
          }
        ]
      }
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Create a booking link

`POST /v1/booking-links` - operationId `booking-links.create`

| Permission | Rate limit |
| --- | --- |
| Calendar view | 4,800 requests a minute per API key |

Creates a link to a member's booking page. `kind` is `person` or `single_use`. `hostMemberId`
is the member whose page the link opens and defaults to you. Another member's page or meeting type needs the
`members` permission.

A person link needs `personId`. Kenso keeps one link per person for each source, campaign, Studio page,
meeting type and host, so asking again returns the same link with `200` instead of `201`. `source`
is `personal`, `campaign`, `reply` or `studio`. When you leave it out, Kenso uses
`campaign` with a `campaignId`, `studio` with an `assetId`, and `personal` otherwise.
`source: campaign` and `stepOrder` need `campaignId`, and `source: studio` needs
`assetId`. Links for email and LinkedIn never use a Kenso domain. With `channel: email`,
`senderAddress` is the From address of the email the link goes in: Kenso serves a campaign email's link from
`cal.` on the sending domain when that host is ready.

A single-use link books one meeting and expires after 30 days. It takes `personId`, `accountId`,
`meetingTypeId`, `hostMemberId`, `channel` and `availability`. `meetingTypeId` defaults
to the host's default type. `availability` gives the link its own weekly hours and date overrides, used
instead of the meeting type's and the host's hours. Calendar busy time, the minimum notice, the booking window,
the buffers and the daily cap still apply. Save the returned `url`: Kenso keeps only a hash of a single-use
link's token and cannot show the URL again.

The response's `id` is the link id that `PATCH /v1/booking-links/{bookingLinkId}` takes.

Errors:

- `400 validation_failed`: `kind` is missing or unknown, a field does not apply to the kind, a field
another field needs is missing, `senderAddress` is not an email address, `accountId` or
`touchId` is not the person's, `hostMemberId` does not host the meeting type, or the host has no
default meeting type.
- `403 forbidden`: you need the `members` permission for another member's page or meeting type, or the
API key is not tied to a member of the workspace.
- `403 permission_denied`: Client seats cannot create booking links.
- `404 not_found`: the person, member, meeting type, account, campaign, touch or Studio page is not in this
workspace, or you cannot see it.
- `409 invalid_state`: no booking domain can serve the link yet, or the meeting type is turned off.
- `503 service_unavailable`: Kenso cannot make booking links right now. Try again in a few minutes.

Requires Meetings view.

Needs the `scheduler` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/booking-links/POST/v1/booking-links)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | no | The kind of link: `person` or `single_use`. |
| `personId` | integer (int64) | no | The person the link is for. Required for a person link. |
| `meetingTypeId` | integer (int64) | no | The meeting type the link books. On a single-use link it defaults to the host's default type. |
| `hostMemberId` | integer (int64) | no | The member whose booking page the link opens. Defaults to you; another member needs the `members` permission. |
| `accountId` | integer (int64) | no | The person's account the booking belongs to. |
| `campaignId` | integer (int64) | no | The campaign the link goes out in, on a person link. |
| `stepOrder` | integer (int32) | no | The campaign step the link goes out in. Needs `campaignId`. |
| `touchId` | integer (int64) | no | The person's touch the link goes out in, on a person link. |
| `assetId` | integer (int64) | no | The Studio page the link sits on, on a person link. |
| `source` | string | no | Where a person link is used: `personal`, `campaign`, `reply` or `studio`. Left out, it is `campaign` with a `campaignId`, `studio` with an `assetId`, and `personal` otherwise. |
| `channel` | string | no | The channel the link goes out on: `email`, `linkedin` or `web`. |
| `senderAddress` | string | no | The From address of the email the link goes in, on a person link with `channel: email`. |
| `availability` | AvailabilitySchedule | no | For single-use links only: the link's own available times, used instead of the meeting type's and the host's. Leave it out, or send null, to use the type's. |

### Response 201

Also answers `200`. `data` is a `BookingLink`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The link's id. A single-use link's times can change later with `PATCH /v1/booking-links/{bookingLinkId}`. |
| `url` | string | The link to send. |
| `kind` | string | The kind of link: `person` or `single_use`. |
| `expiresAt` | string (date-time) | When a single-use link expires (UTC); null for a person link. |
| `availability` | AvailabilitySchedule | A single-use link's own available times; null when it uses the meeting type's, and on person links. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/booking-links" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "person",
  "personId": 812,
  "meetingTypeId": 812,
  "hostMemberId": 812,
  "accountId": 812,
  "campaignId": 812,
  "stepOrder": 1,
  "touchId": 812,
  "assetId": 812,
  "source": "personal",
  "channel": "email",
  "senderAddress": "string",
  "availability": {
    "timeZone": "America/New_York",
    "weekly": {
      "monday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "tuesday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "wednesday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "thursday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "friday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "saturday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "sunday": [
        {
          "start": "string",
          "end": "string"
        }
      ]
    },
    "overrides": [
      {
        "date": "string",
        "ranges": [
          {
            "start": "string",
            "end": "string"
          }
        ]
      }
    ]
  }
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "url": "https://example.com",
    "kind": "person",
    "expiresAt": "2026-09-23T15:02:11Z",
    "availability": {
      "timeZone": "America/New_York",
      "weekly": {
        "monday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "tuesday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "wednesday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "thursday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "friday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "saturday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "sunday": [
          {
            "start": "string",
            "end": "string"
          }
        ]
      },
      "overrides": [
        {
          "date": "string",
          "ranges": [
            {}
          ]
        }
      ]
    }
  }
}
```

## Update a single-use link's times

`PATCH /v1/booking-links/{bookingLinkId}` - operationId `booking-links.update`

| Permission | Rate limit |
| --- | --- |
| Calendar view | 4,800 requests a minute per API key |

Changes the hours of a single-use link you made, for example after you copied it into an email. Send
`availability` with the link's own schedule, in the same shape and rules as on create, or `null` to use
the meeting type's hours again. A schedule here may hold only date overrides. Leaving `availability` out
changes nothing. Returns the link as the list shows it.

Errors:

- `400 validation_failed`: the body is missing, has an unknown field, or the schedule breaks a rule.
- `403 forbidden`: the API key is not tied to a member of the workspace.
- `403 permission_denied`: Client seats cannot change booking links.
- `404 not_found`: the link is not a single-use link you made in this workspace.
- `409 invalid_state`: the link was already used to book (`link_used`) or has expired
(`link_expired`).

Requires Meetings view.

Needs the `scheduler` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/booking-links/PATCH/v1/booking-links/%7BbookingLinkId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `bookingLinkId` | path | integer (int64) | yes | The single-use link's id, from the create response or the list. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `availability` | AvailabilitySchedule | no | The link's own available times, replacing the whole schedule, with the same shape and rules as on create. Null clears it, so the link uses its meeting type's times again. Leave it out to change nothing. |

### Response 200

`data` is a `BookingLinkSummary`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The link's id. |
| `kind` | string | The kind of link: always `single_use`. |
| `meetingTypeId` | integer (int64) | The meeting type the link books. |
| `personId` | integer (int64) | The person the link was made for; null when none was named. |
| `createdAt` | string (date-time) | When the link was made (UTC). |
| `expiresAt` | string (date-time) | When the link expires (UTC). |
| `availability` | AvailabilitySchedule | The link's own available times; null when it uses the meeting type's. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/booking-links/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "availability": {
    "timeZone": "America/New_York",
    "weekly": {
      "monday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "tuesday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "wednesday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "thursday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "friday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "saturday": [
        {
          "start": "string",
          "end": "string"
        }
      ],
      "sunday": [
        {
          "start": "string",
          "end": "string"
        }
      ]
    },
    "overrides": [
      {
        "date": "string",
        "ranges": [
          {
            "start": "string",
            "end": "string"
          }
        ]
      }
    ]
  }
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "kind": "string",
    "meetingTypeId": 812,
    "personId": 812,
    "createdAt": "2026-09-23T15:02:11Z",
    "expiresAt": "2026-09-23T15:02:11Z",
    "availability": {
      "timeZone": "America/New_York",
      "weekly": {
        "monday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "tuesday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "wednesday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "thursday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "friday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "saturday": [
          {
            "start": "string",
            "end": "string"
          }
        ],
        "sunday": [
          {
            "start": "string",
            "end": "string"
          }
        ]
      },
      "overrides": [
        {
          "date": "string",
          "ranges": [
            {}
          ]
        }
      ]
    }
  }
}
```

## Get suggested times for a person

`GET /v1/booking-links/suggested-times` - operationId `booking-links.suggested-times`

| Permission | Rate limit |
| --- | --- |
| Calendar view | 12,000 requests a minute per API key |

Returns up to three open times on a person's own booking link, to offer in a reply. Each time has a `url`
that opens the booking page with that time picked. Opening it does not book.

Query parameters: `personId` is required. `hostMemberId` is the member whose page the link opens and
defaults to you; another member's page needs the `members` permission. `meetingTypeId` must be one of
that member's own personal types and defaults to their default type. `campaignId` is the campaign of the
thread you are answering, so a booking through the link counts for that campaign. `senderAddress` is the
mailbox the reply goes out from: with a campaign, Kenso serves the link from `cal.` on the sending domain when
that host is ready.

The times are for the member the page routes this person to, given in the response's `hostMemberId` and
`routingReason`. Kenso takes the first open time of each day that has one, for up to three days in the next
14 days, counting days in the host's time zone. Kenso creates the person's link when it does not exist yet. A
Client seat creates nothing: it gets times only on a link that already exists for this person.

`status` is `available`, `no_availability`, or `unavailable` with a `reason`. When the
member books through Calendly, Cal.com, HubSpot or Chili Piper, `status` is `external_tool` and
`url` is that tool's link, with no times.

Errors:

- `400 validation_failed`: `personId` is missing, `senderAddress` is not an email address, or
`meetingTypeId` is not one of the member's personal types.
- `403 forbidden`: you need the `members` permission for another member's page, or the API key is not
tied to a member of the workspace.
- `404 not_found`: the person, member, campaign or meeting type is not in this workspace, or you cannot see it.
- `409 invalid_state`: the meeting type is turned off, the member has no meeting type, no booking domain can
serve the link yet, or a Client seat asked for a person who has no link yet.
- `503 service_unavailable`: Kenso cannot make booking links right now. Try again in a few minutes.

Requires Meetings view.

Needs the `scheduler` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/booking-links/GET/v1/booking-links/suggested-times)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `personId` | query | integer (int64) | no | The person to suggest times to, by person id. Required. |
| `meetingTypeId` | query | integer (int64) | no | The meeting type to book, one of the host's own personal types. Omitted uses the host's default type. |
| `hostMemberId` | query | integer (int64) | no | The member whose booking page the link opens, by member id. Omitted means you, and another member's id needs the `members` permission. |
| `campaignId` | query | integer (int64) | no | The campaign of the thread you are answering. A booking through the link then counts for that campaign. |
| `senderAddress` | query | string | no | The mailbox the reply goes out from, as an email address. With `campaignId`, the link uses `cal.` on the sender's domain once that host is ready. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `SuggestedTimes`.

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | Whether there are times: `available`, `no_availability`, `unavailable` (with a `reason`), or `external_tool` when the member books through another tool. |
| `reason` | string | Why there are no times, with `unavailable`, such as `no_host` when no member can take the meeting. |
| `bookingTool` | string | The tool the member books through: `ken` (Kenso's booking page), `calendly`, `cal_com`, `hubspot` or `chili_piper`. |
| `hostMemberId` | integer (int64) | The member the booking page routes this person to. |
| `meetingTypeId` | integer (int64) | The meeting type the times are for. |
| `routingReason` | string | Why the page routes the person to this member, for your members only. |
| `timeZone` | string | The time zone `localStartAt` uses. |
| `url` | string | The person's booking link, or the other tool's link with `external_tool`. |
| `times` | array of SuggestedTime | The suggested times, up to three; empty when there are none. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/booking-links/suggested-times" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "status": "string",
    "reason": "no_host",
    "bookingTool": "string",
    "hostMemberId": 812,
    "meetingTypeId": 812,
    "routingReason": "string",
    "timeZone": "string",
    "url": "https://example.com",
    "times": [
      {
        "startAt": "2026-09-23T15:02:11Z",
        "endAt": "2026-09-23T15:02:11Z",
        "localStartAt": "2026-11-04T09:30:00-05:00",
        "url": "https://example.com"
      }
    ]
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### AvailabilitySchedule

Weekly hours plus date overrides. When Kenso returns a schedule, every weekday is present (an empty list has no times) and the overrides are sorted by date. When you send one, a missing weekday has no times and missing `overrides` means none. Unknown fields are refused.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `timeZone` | string | no | The IANA time zone the hours are in, such as `America/New_York`. Null means each host's own time zone. |
| `weekly` | AvailabilityWeek | no | The hours for each day of the week. |
| `overrides` | array of AvailabilityOverride | no | Up to 100 dates, each once. Each date's ranges replace its weekday's hours; an empty list blocks the date. |

### AvailabilityWeek

The hours for each weekday: up to 6 ranges a day, as `HH:mm` at any whole minute, each starting before it ends, ending by `24:00` and not overlapping another. Ranges that touch are merged, and each day is kept in order.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `monday` | array of AvailabilityRange | no | Monday's hours. |
| `tuesday` | array of AvailabilityRange | no | Tuesday's hours. |
| `wednesday` | array of AvailabilityRange | no | Wednesday's hours. |
| `thursday` | array of AvailabilityRange | no | Thursday's hours. |
| `friday` | array of AvailabilityRange | no | Friday's hours. |
| `saturday` | array of AvailabilityRange | no | Saturday's hours. |
| `sunday` | array of AvailabilityRange | no | Sunday's hours. |

### AvailabilityOverride

One date's hours, used instead of its weekday's.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `date` | string | no | The date, as `YYYY-MM-DD`. |
| `ranges` | array of AvailabilityRange | no | The date's hours. An empty or missing list blocks the whole date. |

### AvailabilityRange

One range of a day.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `start` | string | no | When the range starts, as `HH:mm`. |
| `end` | string | no | When the range ends, as `HH:mm`; `24:00` is midnight at the end of the day. |

### SuggestedTime

One suggested time. Opening its `url` shows the booking page with this time picked, and does not book.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `startAt` | string (date-time) | no | When the meeting would start (UTC). |
| `endAt` | string (date-time) | no | When the meeting would end (UTC). |
| `localStartAt` | string | no | The start in `timeZone` with its offset, like `2026-11-04T09:30:00-05:00`. |
| `url` | string | no | The person's booking link with this time picked. |

All resources: [/docs.md](/docs.md).
