Skip to content

Understory API

This is the reference documentation for the Understory API. Here you can find detailed information about the API endpoints, request and response formats, and authentication methods.

For more general information, go to Documentation.

Preview

You’re exploring an early preview of the Understory API documentation. Take a look around and see what’s available.

Want to help us test and improve it? Share your feedback by clicking the chat icon in the bottom right. We’d love to hear your thoughts!

Download OpenAPI description
index.json
index.yaml
Overview
License
Apache 2.0
Languages
Servers
https://api.understory.io

Booking

Bookings related endpoints.

Operations
Webhooks

Event Availability

Query availability for events.

Event availability is a computed value based on a number of parameters, including:

  • Event capacity and current reservations
  • Resources linked to tickets and bookings (e.g., bikes, kayaks, equipment)
  • Booking cut-off time

The availability response includes both an overall availability status and a breakdown of individual constraints, allowing you to understand exactly what factors are limiting availability for a given event.

Operations

Event

This is a preview of the Events API specification.

The API is not yet available in production.

Operations
Webhooks

Get eventsAlpha

Request

Get all events for the company.

Security
OAuth2(Required scopes:
event.read
)
Query
cursorstring

The cursor for pagination. An empty string indicates the start of the list.

limitinteger(int32)[ 1 .. 500 ]

The maximum number of events to return.

Default 100
fromstring

Filter events starting from this local date-time (inclusive). ISO 8601 date-time without timezone (e.g., 2025-01-15T09:00:00). The value is matched against the event's local start time.

Example: from=2025-01-15T09:00:00
tostring

Filter events up to this local date-time (exclusive). ISO 8601 date-time without timezone (e.g., 2025-01-15T18:00:00). The value is matched against the event's local start time.

Example: to=2025-01-15T18:00:00
curl -i -X GET \
  'https://api.understory.io/v1/events?cursor=string&limit=100&from=2025-01-15T09%3A00%3A00&to=2025-01-15T18%3A00%3A00' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
nextstring

The cursor for the next page. An empty string indicates the end of the list.

itemsArray of objects(Event)
idstringrequired

The unique identifier for the event.

statestringrequired

The state of the event.

Enum"ACTIVE""INACTIVE""CANCELLED""COMPLETED""UNKNOWN"
visibilitystringrequired

The visibility of the event.

Enum"PUBLIC""PRIVATE""UNKNOWN"
experience_idstringrequired

The unique identifier for the experience.

capacityobject(Capacity)required

The capacity of the event.

totalintegerrequired

The total number of seats.

reservedintegerrequired

The number of reserved seats.

sessionsArray of objects(Session)[ 1 .. 10 ] itemsrequired

The sessions for the event.

idstringrequired

The unique identifier for the session.

start_timestring(date-time)required

The start time of the session.

end_timestring(date-time)required

The end time of the session.

timezonestringrequired

The IANA time zone name for the session.

Example: "Europe/Copenhagen"
location_idstringrequired

The unique identifier for the location of the session.

languagesArray of strings(iso-639-1)required

The languages spoken during the session.

Example: ["en"]
created_atstring(date-time)required

The date and time when the event was created.

updated_atstring(date-time)required

The date and time when the event was last updated.

metadataobject(Metadata)

A set of key-value pairs that are attached to the event for storing additional information.

property name*stringadditional property
Response
application/json
{
  "next": "string",
  "items": [
    { … }
  ]
}

Get eventAlpha

Request

Get an event by its ID.

Security
OAuth2(Required scopes:
event.read
)
Path
eventIdstringrequired

The unique identifier for the event.

curl -i -X GET \
  'https://api.understory.io/v1/events/{eventId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstringrequired

The unique identifier for the event.

statestringrequired

The state of the event.

Enum"ACTIVE""INACTIVE""CANCELLED""COMPLETED""UNKNOWN"
visibilitystringrequired

The visibility of the event.

Enum"PUBLIC""PRIVATE""UNKNOWN"
experience_idstringrequired

The unique identifier for the experience.

capacityobject(Capacity)required

The capacity of the event.

totalintegerrequired

The total number of seats.

reservedintegerrequired

The number of reserved seats.

sessionsArray of objects(Session)[ 1 .. 10 ] itemsrequired

The sessions for the event.

idstringrequired

The unique identifier for the session.

start_timestring(date-time)required

The start time of the session.

end_timestring(date-time)required

The end time of the session.

timezonestringrequired

The IANA time zone name for the session.

Example: "Europe/Copenhagen"
location_idstringrequired

The unique identifier for the location of the session.

languagesArray of strings(iso-639-1)required

The languages spoken during the session.

Example: ["en"]
created_atstring(date-time)required

The date and time when the event was created.

updated_atstring(date-time)required

The date and time when the event was last updated.

metadataobject(Metadata)

A set of key-value pairs that are attached to the event for storing additional information.

property name*stringadditional property
Response
application/json
{
  "id": "string",
  "state": "ACTIVE",
  "visibility": "PUBLIC",
  "experience_id": "string",
  "capacity": {
    "total": 0,
    "reserved": 0
  },
  "sessions": [
    { … }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

Event createdAlphaWebhook

Request

Sent when a new event is created for an experience.

Headers
webhook-idstringrequired

Unique identifier for this webhook message. This ID is the same when a webhook is retried due to a previous failure. Use this for deduplication.

webhook-timestampstringrequired

Timestamp of when the webhook was sent, in seconds since epoch. Compare against your system time to prevent replay attacks.

webhook-signaturestringrequired

Base64-encoded HMAC-SHA256 signature for verifying the webhook authenticity. The signature is computed over: {webhook-id}.{webhook-timestamp}.{body}.

Bodyapplication/jsonrequired

Information about the created event.

idstringrequired

Unique identifier for the event.

typestringrequired

The event type.

Value "v1.event.created"
timestampstring(date-time)required

Timestamp of when the event occurred.

payloadobjectrequired

The event-specific payload data.

event_idstringrequired

The unique identifier of the created event.

experience_idstringrequired

The unique identifier of the experience this event belongs to.

host_idstringrequired

The unique identifier of the host managing the event.

session_idsArray of stringsrequired

The unique identifiers of the sessions scheduled for this event.

application/json
{
  "id": "string",
  "type": "v1.event.created",
  "timestamp": "2019-08-24T14:15:22Z",
  "payload": {
    "event_id": "string",
    "experience_id": "string",
    "host_id": "string",
    "session_ids": [ … ]
  }
}

Responses

OK

Event updatedAlphaWebhook

Request

Sent when an event is updated.

Headers
webhook-idstringrequired

Unique identifier for this webhook message. This ID is the same when a webhook is retried due to a previous failure. Use this for deduplication.

webhook-timestampstringrequired

Timestamp of when the webhook was sent, in seconds since epoch. Compare against your system time to prevent replay attacks.

webhook-signaturestringrequired

Base64-encoded HMAC-SHA256 signature for verifying the webhook authenticity. The signature is computed over: {webhook-id}.{webhook-timestamp}.{body}.

Bodyapplication/jsonrequired

Information about the updated event.

idstringrequired

Unique identifier for the event.

typestringrequired

The event type.

Value "v1.event.updated"
timestampstring(date-time)required

Timestamp of when the event occurred.

payloadobjectrequired

The event-specific payload data.

event_idstringrequired

The unique identifier of the updated event.

experience_idstringrequired

The unique identifier of the experience this event belongs to.

host_idstringrequired

The unique identifier of the host managing the event.

session_idsArray of stringsrequired

The unique identifiers of the sessions scheduled for this event.

application/json
{
  "id": "string",
  "type": "v1.event.updated",
  "timestamp": "2019-08-24T14:15:22Z",
  "payload": {
    "event_id": "string",
    "experience_id": "string",
    "host_id": "string",
    "session_ids": [ … ]
  }
}

Responses

OK

Event cancelledAlphaWebhook

Request

Sent when an event is cancelled.

Headers
webhook-idstringrequired

Unique identifier for this webhook message. This ID is the same when a webhook is retried due to a previous failure. Use this for deduplication.

webhook-timestampstringrequired

Timestamp of when the webhook was sent, in seconds since epoch. Compare against your system time to prevent replay attacks.

webhook-signaturestringrequired

Base64-encoded HMAC-SHA256 signature for verifying the webhook authenticity. The signature is computed over: {webhook-id}.{webhook-timestamp}.{body}.

Bodyapplication/jsonrequired

Information about the cancelled event.

idstringrequired

Unique identifier for the event.

typestringrequired

The event type.

Value "v1.event.cancelled"
timestampstring(date-time)required

Timestamp of when the event occurred.

payloadobjectrequired

The event-specific payload data.

event_idstringrequired

The unique identifier of the cancelled event.

host_idstringrequired

The unique identifier of the host managing the event.

application/json
{
  "id": "string",
  "type": "v1.event.cancelled",
  "timestamp": "2019-08-24T14:15:22Z",
  "payload": {
    "event_id": "string",
    "host_id": "string"
  }
}

Responses

OK

Event completedAlphaWebhook

Request

Sent when an event has completed.

For single-session events, this is triggered when the session's end time is reached. For multi-session events, this is triggered when the last session's end time is reached.

Headers
webhook-idstringrequired

Unique identifier for this webhook message. This ID is the same when a webhook is retried due to a previous failure. Use this for deduplication.

webhook-timestampstringrequired

Timestamp of when the webhook was sent, in seconds since epoch. Compare against your system time to prevent replay attacks.

webhook-signaturestringrequired

Base64-encoded HMAC-SHA256 signature for verifying the webhook authenticity. The signature is computed over: {webhook-id}.{webhook-timestamp}.{body}.

Bodyapplication/jsonrequired

Information about the completed event.

idstringrequired

Unique identifier for the event.

typestringrequired

The event type.

Value "v1.event.completed"
timestampstring(date-time)required

Timestamp of when the event occurred.

payloadobjectrequired

The event-specific payload data.

event_idstringrequired

The unique identifier of the completed event.

host_idstringrequired

The unique identifier of the host managing the event.

application/json
{
  "id": "string",
  "type": "v1.event.completed",
  "timestamp": "2019-08-24T14:15:22Z",
  "payload": {
    "event_id": "string",
    "host_id": "string"
  }
}

Responses

OK

Event deletedAlphaWebhook

Request

Sent when an event is deleted.

Headers
webhook-idstringrequired

Unique identifier for this webhook message. This ID is the same when a webhook is retried due to a previous failure. Use this for deduplication.

webhook-timestampstringrequired

Timestamp of when the webhook was sent, in seconds since epoch. Compare against your system time to prevent replay attacks.

webhook-signaturestringrequired

Base64-encoded HMAC-SHA256 signature for verifying the webhook authenticity. The signature is computed over: {webhook-id}.{webhook-timestamp}.{body}.

Bodyapplication/jsonrequired

Information about the deleted event.

idstringrequired

Unique identifier for the event.

typestringrequired

The event type.

Value "v1.event.deleted"
timestampstring(date-time)required

Timestamp of when the event occurred.

payloadobjectrequired

The event-specific payload data.

event_idstringrequired

The unique identifier of the deleted event.

host_idstringrequired

The unique identifier of the host managing the event.

application/json
{
  "id": "string",
  "type": "v1.event.deleted",
  "timestamp": "2019-08-24T14:15:22Z",
  "payload": {
    "event_id": "string",
    "host_id": "string"
  }
}

Responses

OK

Experience

This is a preview of the Experience API specification.

The API is not yet available in production.

Operations
Webhooks

Grow

This is a collection of endpoints related to Understory Grow.

Operations

Order

Orders API allows you to retrieve order information, including line items, transactions and refunds.

Operations

Test

These endpoints are for testing purposes only.

You can use them to verify that your integration authentication works as intended.

Operations

Webhook

Webhook subscription management and event delivery.

Webhooks are sent to subscriber endpoints when events occur related to experiences, events, and bookings.

Operations
Webhooks