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.

OperationsWebhooks

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.

OperationsWebhooks

Experience

This is a preview of the Experience API specification.

The API is not yet available in production.

OperationsWebhooks

Get experiencesAlpha

Request

Get all experiences for the company.

Security
OAuth2
Query
cursorstring

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

limitinteger(int32)

The maximum number of experiences to return.

Default 100
Headers
Accept-Languagestring(AcceptLanguageHeader)required

Combination of language and country/region. The format is a lowercase ISO 639-1 language code followed by an optional hyphen and an uppercase ISO 3166-1 country code.

If no value matches what is available in the host's Storefront, an error response is returned.

You can optionally provide multiple language-country pairs with a priority, separated by commas based on content negotiation.

Example: en-GB; q=1.0, en-US; q=0.8
curl -i -X GET \
  'https://api.understory.io/v1/experiences?cursor=string&limit=100' \
  -H 'Accept-Language: en-GB; q=1.0, en-US; q=0.8' \
  -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(Experience)
idstringrequired

The unique identifier for the experience.

typestringrequired

The type of experience.

Enum"MULTI_SESSION""SINGLE_SESSION"
statestringrequired

The state of the experience.

Enum"ACTIVE""INACTIVE""ARCHIVED""DELETED""UNKNOWN"
namestringrequired

The name of the experience.

created_atstring(date-time)required

Timestamp of when the experience was created.

updated_atstring(date-time)required

Timestamp of when the experience was last updated.

descriptionstring(MarkdownText)
tag_idsArray of strings

Array of tag IDs that are associated with the experience.

Tags can be used to categorize and filter experiences.

mediaArray of Image (object) or Video (object)(Media)

Media attached to the experience.

One of:
typestringrequired
Value"IMAGE"
urlstring(uri)required

URL of the image.

mime_typestringrequired

MIME type of the image (e.g., image/jpeg).

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

Get experienceAlpha

Request

Get an experience by its ID.

Security
OAuth2
Path
experienceIdstringrequired

The unique identifier of the experience.

Headers
Accept-Languagestringrequired

Combination of language and country/region. The format is a lowercase ISO 639-1 language code followed by an optional hyphen and an uppercase ISO 3166-1 country code.

If no value matches what is available, an error response is returned.

Example: en-GB; q=1.0, en-US; q=0.8
curl -i -X GET \
  'https://api.understory.io/v1/experiences/{experienceId}' \
  -H 'Accept-Language: en-GB; q=1.0, en-US; q=0.8' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstringrequired

The unique identifier for the experience.

typestringrequired

The type of experience.

Enum"MULTI_SESSION""SINGLE_SESSION"
statestringrequired

The state of the experience.

Enum"ACTIVE""INACTIVE""ARCHIVED""DELETED""UNKNOWN"
namestringrequired

The name of the experience.

created_atstring(date-time)required

Timestamp of when the experience was created.

updated_atstring(date-time)required

Timestamp of when the experience was last updated.

descriptionstring(MarkdownText)
tag_idsArray of strings

Array of tag IDs that are associated with the experience.

Tags can be used to categorize and filter experiences.

mediaArray of Image (object) or Video (object)(Media)

Media attached to the experience.

One of:
typestringrequired
Value"IMAGE"
urlstring(uri)required

URL of the image.

mime_typestringrequired

MIME type of the image (e.g., image/jpeg).

metadataobject(Metadata)
property name*stringadditional property
Response
application/json
{
  "id": "string",
  "type": "MULTI_SESSION",
  "state": "ACTIVE",
  "name": "string",
  "description": "string",
  "tag_ids": [
    "string"
  ],
  "media": [
    { … }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

Get information requestsAlpha

Request

Information requests describes additional information that is collected during the booking flow.

These are usually presented as additional questions to be answered by the guest.

Security
OAuth2
Path
experienceIdstringrequired

The ID of the experience.

Query
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 100, maximum 100.

Default 100
Headers
Accept-Languagestring(AcceptLanguageHeader)required

Combination of language and country/region. The format is a lowercase ISO 639-1 language code followed by an optional hyphen and an uppercase ISO 3166-1 country code.

If no value matches what is available in the host's Storefront, an error response is returned.

You can optionally provide multiple language-country pairs with a priority, separated by commas based on content negotiation.

Example: en-GB; q=1.0, en-US; q=0.8
curl -i -X GET \
  'https://api.understory.io/v1/experiences/{experienceId}/information-requests?cursor=string&limit=100' \
  -H 'Accept-Language: en-GB; q=1.0, en-US; q=0.8' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
nextstring

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

itemsArray of TextInformationRequest (object)(InformationRequest)
TextInformationRequest (object)(InformationRequest)
Response
application/json
{
  "next": "string",
  "items": [
    { … }
  ]
}

Get ticket variantsAlpha

Request

Ticket variants describe the ticket options available for booking an experience.

Security
OAuth2
Path
experienceIdstringrequired

The ID of the experience.

Query
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 100, maximum 100.

Default 100
Headers
Accept-Languagestring(AcceptLanguageHeader)required

Combination of language and country/region. The format is a lowercase ISO 639-1 language code followed by an optional hyphen and an uppercase ISO 3166-1 country code.

If no value matches what is available in the host's Storefront, an error response is returned.

You can optionally provide multiple language-country pairs with a priority, separated by commas based on content negotiation.

Example: en-GB; q=1.0, en-US; q=0.8
curl -i -X GET \
  'https://api.understory.io/v1/experiences/{experienceId}/ticket-variants?cursor=string&limit=100' \
  -H 'Accept-Language: en-GB; q=1.0, en-US; q=0.8' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
nextstring

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

itemsArray of objects(TicketVariant)
idstringrequired

The unique identifier of the ticket variant.

namestringrequired

The name of the ticket variant.

priceobject(PriceAmount)required
currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
vat_amountobject(PriceAmount)required
currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
descriptionstring

The description of the ticket variant.

add_on_variantsArray of objects(AddOnVariant)

List of add-on variants that can be added to this ticket variant.

idstringrequired

The unique identifier of the add-on variant.

namestringrequired

The name of the add-on variant.

priceobject(PriceAmount)required
currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
vat_amountobject(PriceAmount)required
currencystringrequired

The ISO 4217 currency code.

Example: "USD"
valueintegerrequired

The price in the smallest currency unit (e.g. cents for USD).

Example: 2500
exponentintegerrequired

The number of decimal places for the currency.

Example: 2
descriptionstring

The description of the add-on variant.

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

Experience createdPreviewWebhook

Request

Sent when a new experience is created.

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 experience.

experience_idstringrequired

The unique identifier of the created experience.

host_idstringrequired

The unique identifier of the host that owns the experience.

application/json
{
  "experience_id": "string",
  "host_id": "string"
}

Responses

OK

Experience updatedPreviewWebhook

Request

Sent when an experience 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 experience.

experience_idstringrequired

The unique identifier of the updated experience.

host_idstringrequired

The unique identifier of the host that owns the experience.

application/json
{
  "experience_id": "string",
  "host_id": "string"
}

Responses

OK

Experience deletedPreviewWebhook

Request

Sent when an experience 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 experience.

experience_idstringrequired

The unique identifier of the deleted experience.

host_idstringrequired

The unique identifier of the host that owned the experience.

application/json
{
  "experience_id": "string",
  "host_id": "string"
}

Responses

OK

Grow

This is a collection of endpoints related to Understory Grow.

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.

OperationsWebhooks