Skip to content

Availability

An Availability is a period an experience can be booked for, together with the constraints that decide whether it can be booked right now.

An availability covers either a concrete Event or a timeslot that has no event yet. Experiences that sell timeslots offer several durations from the same start time, and the event is created only when someone books. Both kinds carry an id that addresses the availability, so a caller can re-read one it already holds without searching the window around it again.

Timeslots are not bookable yet

Timeslots are not bookable yet through the public API.

Events are unaffected: read availability here, then book with the event_id carried on the EVENT subject using Create Booking.

Every constraint that applies to an availability is returned whether it passes or fails, so callers can show why an availability is unavailable, or how much of it is left while it still is.

Operations

Get Availabilities
Preview

Request

Get the availabilities of an experience within a time window.

Use this to render a calendar or a time picker. For an availability you already hold an id for, prefer Get Availability. The response is paginated; pass the returned next cursor on subsequent calls to continue.

Events and timeslots the host has closed to new bookings are left out, unless the host exempted the event.

This is a read: it creates nothing and has no side effects. The body is optional — omit it to get the first page of availabilities from the current time onwards.

Security
OAuth2(Required scopes: experience.read)
Path
experienceIdstringrequired

The unique identifier of the experience to compute availability for.

Bodyapplication/json
fromstring

Return availabilities starting on or after this local date-time (inclusive). ISO 8601 date-time without a timezone offset (e.g. 2026-07-14T08:00:00), interpreted in the timezone of the location its subject runs at. Defaults to the current time — pass it explicitly to look into the past.

Example:"2026-07-14T08:00:00"
tostring

Return availabilities starting before this local date-time (exclusive). ISO 8601 date-time without a timezone offset (e.g. 2026-07-15T00:00:00), interpreted in the timezone of the location its subject runs at. Omit it to leave the window open-ended.

Example:"2026-07-15T00:00:00"
filterobject(AvailabilityFilter)

Narrows which availabilities the window returns.

cursorstring

Pagination cursor for fetching the next page of results. Omit or pass an empty string to start from the beginning of the list.

limitinteger, (int32), [ 1 .. 100 ]

Maximum number of items to return per page. Defaults to 50, maximum 100.

Default:50
curl -i -X POST \
  'https://api.understory.io/v1/experiences/{experienceId}/availabilities' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "2026-07-14T08:00:00",
    "to": "2026-07-15T00:00:00",
    "filter": {
      "event_ids": [
        "string"
      ],
      "location_ids": [
        "string"
      ],
      "durations": [
        "PT1H30M"
      ]
    },
    "cursor": "string",
    "limit": 50
  }'

Responses

OK

Bodyapplication/json
itemsArray of objects(Availability)required

The availabilities matching the query, ordered by start time.

nextstring

Cursor for the next page of results. An empty string or absent value indicates the end of the list.

Response
{
  "items": [
    { … }
  ],
  "next": "string"
}