:::endpoint GET /v1/me/calendar/availability

Give it a guest list and a length, get back the first moments everybody is free.
The account asking is always one of the party.

:::warning It sees what you see, and no more
This is not a free and busy service over the whole firm. A colleague whose
calendar is not shared with this account comes back in `meta.people` with
`visible: false`, and the slots say nothing about them. Sharing a calendar at
the `busy` level is what makes somebody schedulable without letting anybody read
their diary.
:::

The available hours each person sets in the calendar narrow it, each in their
own timezone, together with any extra available time they added for a single
day. Somebody who has never set any is available Monday to Friday,
nine until five. Appointments that last
all day do not block: a holiday should and a "quarterly numbers due" should not,
and there is no way to tell them apart.

## Request

| Parameter  | Description                                                          |
| ---------- | -------------------------------------------------------------------- |
| `guests[]` | Email addresses. Anyone who does not work here comes back as unknown |
| `minutes`  | How long the meeting is. Between 5 and 480, defaults to 60           |
| `from`     | ISO 8601, where to start looking. Defaults to now                    |
| `days`     | How far ahead. Between 1 and 30, defaults to 14                      |

```bash
curl -G https://api.proppertrading.com/v1/me/calendar/availability \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
  --data-urlencode "guests[]=tom@acmefunded.com" \
  --data-urlencode "minutes=30" \
  --data-urlencode "days=7"
```

## Response

```json
{
    "data": [
        {
            "object": "time_slot",
            "starts_at": "2026-08-24T09:00:00+00:00",
            "ends_at": "2026-08-24T09:30:00+00:00"
        },
        {
            "object": "time_slot",
            "starts_at": "2026-08-24T09:15:00+00:00",
            "ends_at": "2026-08-24T09:45:00+00:00"
        }
    ],
    "meta": {
        "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey",
        "people": [
            {
                "name": "Tom de Vries",
                "email": "tom@acmefunded.com",
                "visible": true
            }
        ]
    }
}
```

Slots start on the quarter hour and overlap on purpose: 09:00 and 09:15 are two
answers to the same question, not a mistake. At most six per day and twenty four
in all, so a free Monday does not fill the list before Tuesday is reached.

An empty `data` means no moment in the window suits everybody. A shorter meeting
or a wider `days` is usually the answer.

## Errors

| Status | Code                     | Meaning                                              |
| ------ | ------------------------ | ---------------------------------------------------- |
| 400    | `validation_failed`      | A parameter was out of range. `error.param` names it |
| 400    | `invalid_date`           | `from` was not ISO 8601                              |
| 403    | `insufficient_scope`     | This device does not hold `calendar:read`            |
| 403    | `calendar_not_permitted` | The account may not open a calendar at all           |