# Free time

> Every free time endpoint, generated from the API's own schemas.

Base URL `https://pidgeon.ai/api/v1`. Every request carries `Authorization: Bearer pgn_live_…`. The machine-readable version of this page is https://pidgeon.ai/openapi.json.

## GET /calendar/free-time

When several addresses are all free

The stretches in a window when every address in `identity_ids` is free, at least `duration_minutes` long. Busy is a timed event that is not cancelled and that the address has not declined; tentative counts as busy, all-day events do not. `day_start` and `day_end` limit it to working hours, read in `timezone` (the first address’s calendar zone by default), and each slot carries its wall times in that zone too. Needs `read` on every address. It books nothing.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `identity_ids` | string | yes |  |
| `after` | date-time | no |  |
| `before` | date-time | no |  |
| `duration_minutes` | number | no |  |
| `day_start` | string | no |  |
| `day_end` | string | no |  |
| `timezone` | string | no |  |
| `skip_weekends` | enum | no |  One of: `true`, `false`. |

**Responses**

- `200` The free time.
- `400` The request is not valid. `error.field` names the input at fault when there is one.
- `401` No API key, or one that is not valid.
- `403` Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
- `404` No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
- `409` It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
- `429` Rate limited. `X-RateLimit-Reset` says when to retry.
- `500` Something went wrong on our side. Retry; if it keeps happening, tell us.
- `503` Something this needs is not answering right now. Retry in a moment.