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

Working hours narrow it, each person's in their own timezone. Somebody who has
never set any works 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           |