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

Experience

This is a preview of the Experience API specification.

The API is not yet available in production.

Operations
Webhooks

Get experiencesAlpha

Request

Get all experiences for the company.

Security
OAuth2(Required scopes:
experience.read
)
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

A lowercase ISO 639-1 language code (e.g. "da"), optionally followed by a hyphen and an uppercase ISO 3166-1 country code (e.g. "en-US").

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)

A detailed description of the experience.

The description is in markdown format, and can include rich text, links, and lists.

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 any(Media)

Media attached to the experience.

typestringrequired
Value"IMAGE"
Discriminator
urlstring(uri)required

URL of the image.

mime_typestringrequired

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

metadataobject(Metadata)

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

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

Get experienceAlpha

Request

Get an experience by its ID.

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

The unique identifier of the experience.

Headers
Accept-Languagestringrequired

A lowercase ISO 639-1 language code (e.g. "da"), optionally followed by a hyphen and an uppercase ISO 3166-1 country code (e.g. "en-US").

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)

A detailed description of the experience.

The description is in markdown format, and can include rich text, links, and lists.

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 any(Media)

Media attached to the experience.

typestringrequired
Value"IMAGE"
Discriminator
urlstring(uri)required

URL of the image.

mime_typestringrequired

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

metadataobject(Metadata)

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

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(Required scopes:
experience.read
)
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

A lowercase ISO 639-1 language code (e.g. "da"), optionally followed by a hyphen and an uppercase ISO 3166-1 country code (e.g. "en-US").

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 any(InformationRequest)
idstringrequired

The unique identifier for this information request.

typestringrequired

The type of information request, determining the expected input method.

Value"TEXT"
Discriminator
requiredbooleanrequired

Indicates whether this information request must be answered.

scopestringrequired

Defines at what scope this information is collected.

If the scope is BOOKING, the information is collected once per booking.

If the scope is TICKET, the information is collected for each ticket in the booking, eg. "What size of bicycle do you want?".

Enum"BOOKING""TICKET""UNSPECIFIED"
questionstringrequired

The question presented to the guest.

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

Get ticket variantsAlpha

Request

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

Security
OAuth2(Required scopes:
experience.read
)
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

A lowercase ISO 639-1 language code (e.g. "da"), optionally followed by a hyphen and an uppercase ISO 3166-1 country code (e.g. "en-US").

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

The price of the ticket variant.

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

The VAT amount of the ticket variant.

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

The price of the add-on variant.

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

The VAT amount of the add-on variant.

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 createdAlphaWebhook

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.

idstringrequired

Unique identifier for the event.

typestringrequired

The event type.

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

Timestamp of when the event occurred.

payloadobjectrequired

The event-specific payload data.

experience_idstringrequired

The unique identifier of the created experience.

host_idstringrequired

The unique identifier of the host that owns the experience.

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

Responses

OK

Experience updatedAlphaWebhook

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.

idstringrequired

Unique identifier for the event.

typestringrequired

The event type.

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

Timestamp of when the event occurred.

payloadobjectrequired

The event-specific payload data.

experience_idstringrequired

The unique identifier of the updated experience.

host_idstringrequired

The unique identifier of the host that owns the experience.

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

Responses

OK

Experience deletedAlphaWebhook

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.

idstringrequired

Unique identifier for the event.

typestringrequired

The event type.

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

Timestamp of when the event occurred.

payloadobjectrequired

The event-specific payload data.

experience_idstringrequired

The unique identifier of the deleted experience.

host_idstringrequired

The unique identifier of the host that owned the experience.

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

Responses

OK

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