Skip to content

Find free times

GET
/api/v1/availability

Free times at the key's own organization, from the same slot engine its booking page uses, so a time this returns is one POST /api/v1/reservations or POST /api/v1/appointments will accept (until someone else books it). Shared: the organization's engine decides the question.

  • A table-reservations venue: date and partySize.
  • An appointments business: date and serviceId, optionally providerId (omit it for any available team member; each slot then names the providerId it was found for).

days walks forward from date, up to 14 days in one call. Each day carries its slots and, for a venue, the reason an empty day is empty (closed, full, too_large and so on), so a fully booked day and a closed one never look alike.

Appointment start times sit on one grid per day (behaviour change, 2026-10-13): every appointmentSlotMinutes from the business's opening time that day, or from midnight when it has no opening hours. A team member whose hours start off that grid joins it at the next tick, so with any available team member the slots no longer mix, say, 9:00 and 9:10 starters. The public MCP's find_appointment_times answers from the same engine and changed the same way.

Slot times are the venue's wall clock wearing a Z, exactly like startsAt on a booking. Send one back to create unchanged; never convert it, or it moves by the venue's whole offset.

Also limited per calling IP, 240 requests a minute, by the booking page's own limiter: a 429 here can come from either limit, and both carry Retry-After.

Authorization

bearerApiKey availability:read
AuthorizationBearer <token>

Build with a test key (sk_test_...): it works only in your API sandbox and never emails or texts anyone. Scopes, errors and limits.

In: header

Scope: availability:read

Query Parameters

date*string

The first day, YYYY-MM-DD, on the venue's calendar.

Formatdate
days?integer

How many days from date.

Range1 <= value <= 14
Default1
partySize?integer

Required for a table-reservations venue.

Range1 <= value <= 30
serviceId?string

Required for an appointments business.

Formatuuid
providerId?string

Appointments only. Omit for any available team member.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/availability?date=2019-08-24"
{  "data": {    "businessType": "appointments",    "banner": "string",    "days": [      {        "date": "2019-08-24",        "slots": [          {            "startsAt": "2019-08-24T14:15:22Z",            "providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24",            "periodName": "string"          }        ],        "reason": "string",        "dateNote": "string",        "closedReason": "string"      }    ]  }}