# Availability API – Tiempo > Ask what can be booked before you show times to a customer. Source: https://tiempo.one/docs/availability Ask what can be booked before you show times to a customer. The same engine checks every booking, so a time it offers will be accepted unless someone takes it first. ## Find open times `POST /v1/availability` Every start time on a grid where all segments fit, with the candidates free at each. Give several resources in a segment for “anyone available”. Give the length on each segment, or once as duration_minutes when everything runs together; then duration_overrides gives candidates who take a different time their own length, and each slot is one possible booking (a start can appear once per length). Pass a booking id in exclude_bookings to search as if it weren’t there, for rescheduling. The grid is the business’s (slot_interval_minutes and slot_alignment on the account) unless the search gives interval_minutes or slot_alignment. Send the business’s id in `Tiempo-Account`. ### Body parameters - `from` (timestamp, required) Start of the window. - `to` (timestamp, required) End of the window. - `timezone` (string) IANA name, for example Europe/London. - `interval_minutes` (integer) Spacing of start times. Defaults to the business’s slot_interval_minutes. - `slot_alignment` (string) midnight: starts every interval from local midnight. opening: from the start of each stretch of working hours, so a 09:20 opening offers 09:20. A business defaults to midnight; a search, to its business’s. - `location` (string) A location id. - `segments` (array of objects, required) The time to hold: one entry per resource and period. Segments can be on different resources and needn’t touch. - `resources` (array of strings, required) Candidate resource ids in your order of preference; Tiempo takes the first that fits. - `offset_minutes` (integer) Minutes after the start time the segment begins. Defaults to 0. - `duration_minutes` (integer) Length of the segment; or, on a search, one length for every segment when they all run together (then segments give no length or offset). - `quantity` (integer) Units of capacity to take. Defaults to 1 (for blocks, the whole capacity). - `buffer_before_minutes` (integer) Minutes the resource is also held before the time (travel, setup), 0–1440. On a booking segment it overrides the resource’s default; the appointment’s start and end don’t change. - `buffer_after_minutes` (integer) Minutes the resource is also held after the time (cleanup, turnaround), 0–1440. On a booking segment it overrides the resource’s default. Buffers must fit in working hours and can’t overlap blocks or other bookings. - `exclude_bookings` (array of strings) Booking ids to ignore, for example the one being rescheduled. - `duration_minutes` (integer) Length of the segment; or, on a search, one length for every segment when they all run together (then segments give no length or offset). - `duration_overrides` (map) With duration_minutes on a search: a different length for some candidates of one segment, by resource id (a stylist who’s quicker). The other segments run for the same length as whoever it is. POST /v1/availability ```bash curl -X POST "https://api.tiempo.one/v1/availability" \ -H "Authorization: Bearer tpt_4qZ8m1VwXc0L…" \ -H "Tiempo-Account: acct_01m42yt93ayvyrwr3yczhv6yhw" \ -H "Content-Type: application/json" \ -d '{ "from": "2026-11-16T09:00:00Z", "to": "2026-11-16T13:00:00Z", "interval_minutes": 15, "segments": [ { "resources": [ "res_ann", "res_bob" ], "duration_minutes": 45 } ] }' ``` 200Response ```json { "object": "availability", "from": "2026-11-16T09:00:00Z", "to": "2026-11-16T13:00:00Z", "timezone": "Europe/London", "interval_minutes": 15, "slots": [ { "start": "2026-11-16T10:00:00Z", "end": "2026-11-16T10:45:00Z", "segments": [ { "start": "2026-11-16T10:00:00Z", "end": "2026-11-16T10:45:00Z", "resources": [ "res_bob" ] } ] }, { "start": "2026-11-16T10:15:00Z", "end": "2026-11-16T11:00:00Z", "segments": [ { "start": "2026-11-16T10:15:00Z", "end": "2026-11-16T11:00:00Z", "resources": [ "res_bob" ] } ] }, { "start": "2026-11-16T10:45:00Z", "end": "2026-11-16T11:30:00Z", "segments": [ { "start": "2026-11-16T10:45:00Z", "end": "2026-11-16T11:30:00Z", "resources": [ "res_ann", "res_bob" ] } ] } ] } ``` ## Get a calendar `GET /v1/availability/calendar` For each resource over up to 62 days: working hours, blocks, remaining free capacity, and a status per local day (available, fully booked, blocked, not working). Repeat resource for several. Send the business’s id in `Tiempo-Account`. ### Query parameters - `resource` (string) Only those involving this resource. On the calendar, repeat it for several. - `from` (timestamp) Only those ending after this instant. - `to` (timestamp) Only those starting before this instant. - `location` (string) Only those at this location. - `timezone` (string) The timezone of from_date and to_date. Defaults to the business’s (for the calendar, the location’s first). GET /v1/availability/calendar ```bash curl "https://api.tiempo.one/v1/availability/calendar?resource=res_ann&resource=res_bob&from=2026-11-16T00:00:00Z&to=2026-11-23T00:00:00Z" \ -H "Authorization: Bearer tpt_4qZ8m1VwXc0L…" \ -H "Tiempo-Account: acct_01m42yt93ayvyrwr3yczhv6yhw" ``` 200Response ```json { "object": "…", "from": "2026-11-16T10:00:00Z", "to": "2026-11-16T10:00:00Z", "timezone": "…", "location": "…", "resources": [ { "resource": "…", "working": [ null ], "blocked": [ null ], "free": [ null ], "days": [ null ] } ] } ``` The machine-readable description is at [/openapi.json](https://tiempo.one/openapi.json). Try calls in [Swagger UI](https://tiempo.one/swagger-ui.html).[Tiempo home](https://tiempo.one/)[Dashboard](https://tiempo.one/app)