Skip to content

Understory API (0.1.0)

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

This is an early version of the Bookings API specification.

Most of these APIs are available in production for testing. Endpoints marked as "Preview" are not yet available in production.

Breaking changes might be introduced, but the overall specification is close to stable.

Operations

Experience

This is a preview of the Experience API specification.

The API is not yet available in production.

Operations

Get information requestsPreview

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

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

limitinteger(int32)

The maximum number of requests 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 negotation.

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

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

itemsArray of objects(InformationRequest)
idstringrequired
typestringrequired

What type of response is expected from the guest.

This will be extended in the future with additional types, eg. MULTI_CHOICE.

Value"TEXT"
requiredbooleanrequired

Indicates whether this information request is required to be answered.

scopeanyrequired

Defines at what scope this information is collected.

If the scope is BOOKING, the information is collected once per booking, eg. "Something something".

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"
labelstringrequired

The display label for the information request.

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

Get ticket variantsPreview

Request

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

Security
OAuth2
Path
experienceIdstringrequired

The ID of the experience.

Query
cursorstring

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

limitinteger(int32)

The maximum number of requests 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 negotation.

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

The cursor for the next page. An empty string 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": [
    { … }
  ]
}

Get experiencesPreview

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

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""ARCHIVED""DELETED"
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 objects(Media)

Media attached to the experience.

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

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

example_keystring

Example of a metadata key.

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

Get experiencePreview

Request

Get an experience by its ID.

Security
OAuth2
Path
experienceIdstringrequired
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 negotation.

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""ARCHIVED""DELETED"
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 objects(Media)

Media attached to the experience.

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

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

example_keystring

Example of a metadata key.

property name*anyadditional 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": {
    "example_key": "string"
  }
}

Event

This is a preview of the Events API specification.

The API is not yet available in production.

Operations

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