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.

The API is available in production for testing. Breaking changes might be introduced, but the overall specification is close to stable.

Operations

Event

This is a preview of the Events API specification.

The API is not yet available in production.

Operations

Experience

This is a preview of the Experience API specification.

The API is not yet available in production.

Operations

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 RegularExperience (object) or SharedExperience (object)(Experience)
One of:
is_sharedbooleanrequired

This is a regular experience, i.e., is not a shared experience.

Default false
statusstringrequired

Indicates the status of the experience.

Enum"ACTIVE""INACTIVE""ARCHIVED""DRAFT"
idstringrequired

The unique identifier for the experience.

company_idstringrequired
cutoffobjectrequired

The cutoff time for booking an event.

relative_tostringrequired

Indicates the reference point of the cutoff time.

Enum"BEFORE_EVENT_START""AFTER_EVENT_START""BEFORE_EVENT_END"
durationstring(ISO 8601)required

The duration relative to the reference point. For example, if the reference point is BEFORE_EVENT_START and the duration is PT1H30M then the cutoff time is 1 hour and 30 minutes before the event start time.

Example: "PT2H30M"
namestringrequired

The name of the experience.

created_atstring(date-time)required

Timestamp of when the booking was created.

updated_atstring(date-time)required

Timestamp of when the booking was last updated.

information_requestsArray of objects(InformationRequest)required

Contain any questions to be asked to the guest during checkout.

idstringrequired
requiredbooleanrequired
scopeanyrequired
Enum"BOOKING""TICKET"
requeststringrequired
languagesArray of strings(iso-639-1)(LanguageCode)required

Array of languages the experience is offered in.

Elements are two-letter ISO 639-1 langauge code format.

mediaobjectrequired

Media attached to the experience.

coverArray of any(Media)required
typestringrequired
Value"IMAGE"
Discriminator
urlstring(uri)required
mime_typestringrequired
preview_urlstring(uri)
primary_imageobject(Image)
typestringrequired
Value"IMAGE"
urlstring(uri)required
mime_typestringrequired
preview_urlstring(uri)
priceobject(Price)required

Detailed price information for the experience.

display_variant_idstring(uuid)required

The ID of the variant that should be used for display price.

variantsArray of objectsrequired

All the variants of tickets offered for the experience.

idstringrequired

Unique ID for the variant.

namestringrequired

Name of the variant.

priceobject(PriceBreakdown)required
currencystringrequired

The currency of the price.

Example: "DKK"
vat_inclusive_centsnumber(int)required

The price in cents including VAT.

Example: 100
vat_amount_centsnumber(int)required

The VAT amount in cents.

Example: 20
vat_exlusive_centsnumber(int)required

The price in cents excluding VAT.

Example: 80
vat_settingobjectrequired
countrystringrequired

The country code for the VAT setting.

Example: "DK"
vat_categorystringrequired

The VAT category for the price.

tax_typestringrequired

The tax type for the price.

Enum"VAT""SALES_TAX""GENERIC"
ratenumber(double)[ 0 .. 0.99 ]required

The VAT rate.

Example: 0.25
exemptbooleanrequired

Indicates if the price is exempt from VAT.

Default false
minstring
explanationstring

A description of the variant.

addonsArray of objects(Addons)

Addons that can be selected for the variant.

idstring(uuid)required

A unique identifier for the addon.

namestringrequired

The name of the addon.

priceobject(PriceBreakdown)required

The price of the addon.

currencystringrequired

The currency of the price.

Example: "DKK"
vat_inclusive_centsnumber(int)required

The price in cents including VAT.

Example: 100
vat_amount_centsnumber(int)required

The VAT amount in cents.

Example: 20
vat_exlusive_centsnumber(int)required

The price in cents excluding VAT.

Example: 80
vat_settingobjectrequired
countrystringrequired

The country code for the VAT setting.

Example: "DK"
vat_categorystringrequired

The VAT category for the price.

tax_typestringrequired

The tax type for the price.

Enum"VAT""SALES_TAX""GENERIC"
ratenumber(double)[ 0 .. 0.99 ]required

The VAT rate.

Example: 0.25
exemptbooleanrequired

Indicates if the price is exempt from VAT.

Default false
explanationstring

An explanation or description of the addon.

capacityinteger(int)required

The total capacity of the experience.

tag_idsArray of strings(uuid)required

Array of tag IDs that are associated with the experience.

Tags are used to categorize and filter experiences.

visibilitystringrequired

Describes the visibility of the experience.

If visibility is set to PRIVATE it should not be listed in public places like pages, widgets. Private experiences are used to allow for booking events by hosts them selves, e.g. private tours.

Enum"PUBLIC""PRIVATE"
practical_infostring(MarkdownText)

A descriptive text about the experience.

what_is_includedstring(MarkdownText)

Information about what is included in the experience. In bullet point or numbered format with each point seperated by a new line character.

metadataobject
created_bystring

The user ID of the person who created the experience.

property name*anyadditional property
location_idsArray of stringsnon-empty

All the location IDs where the experience is offered.

capacity_unitSINGLE (object) or GROUP (object)

Indicates unit of an experience.

Depending on the type, the following options are available:

  • SINGLE => Tickets sold individually.
  • GROUP => Tickets sold in a range defined by min_participants and max_participants.
One of:

Indicates unit of an experience.

Depending on the type, the following options are available:

  • SINGLE => Tickets sold individually.
  • GROUP => Tickets sold in a range defined by min_participants and max_participants.
typestringrequired

Tickets sold individually.

Value"SINGLE"
namestring

A custom name for the slot/seat/ticket.

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
One of:
is_sharedbooleanrequired

This is a regular experience, i.e., is not a shared experience.

Default false
statusstringrequired

Indicates the status of the experience.

Enum"ACTIVE""INACTIVE""ARCHIVED""DRAFT"
idstringrequired

The unique identifier for the experience.

company_idstringrequired
cutoffobjectrequired

The cutoff time for booking an event.

relative_tostringrequired

Indicates the reference point of the cutoff time.

Enum"BEFORE_EVENT_START""AFTER_EVENT_START""BEFORE_EVENT_END"
durationstring(ISO 8601)required

The duration relative to the reference point. For example, if the reference point is BEFORE_EVENT_START and the duration is PT1H30M then the cutoff time is 1 hour and 30 minutes before the event start time.

Example: "PT2H30M"
namestringrequired

The name of the experience.

created_atstring(date-time)required

Timestamp of when the booking was created.

updated_atstring(date-time)required

Timestamp of when the booking was last updated.

information_requestsArray of objects(InformationRequest)required

Contain any questions to be asked to the guest during checkout.

idstringrequired
requiredbooleanrequired
scopeanyrequired
Enum"BOOKING""TICKET"
requeststringrequired
languagesArray of strings(iso-639-1)(LanguageCode)required

Array of languages the experience is offered in.

Elements are two-letter ISO 639-1 langauge code format.

mediaobjectrequired

Media attached to the experience.

coverArray of any(Media)required
typestringrequired
Value"IMAGE"
Discriminator
urlstring(uri)required
mime_typestringrequired
preview_urlstring(uri)
primary_imageobject(Image)
typestringrequired
Value"IMAGE"
urlstring(uri)required
mime_typestringrequired
preview_urlstring(uri)
priceobject(Price)required

Detailed price information for the experience.

display_variant_idstring(uuid)required

The ID of the variant that should be used for display price.

variantsArray of objectsrequired

All the variants of tickets offered for the experience.

idstringrequired

Unique ID for the variant.

namestringrequired

Name of the variant.

priceobject(PriceBreakdown)required
currencystringrequired

The currency of the price.

Example: "DKK"
vat_inclusive_centsnumber(int)required

The price in cents including VAT.

Example: 100
vat_amount_centsnumber(int)required

The VAT amount in cents.

Example: 20
vat_exlusive_centsnumber(int)required

The price in cents excluding VAT.

Example: 80
vat_settingobjectrequired
countrystringrequired

The country code for the VAT setting.

Example: "DK"
vat_categorystringrequired

The VAT category for the price.

tax_typestringrequired

The tax type for the price.

Enum"VAT""SALES_TAX""GENERIC"
ratenumber(double)[ 0 .. 0.99 ]required

The VAT rate.

Example: 0.25
exemptbooleanrequired

Indicates if the price is exempt from VAT.

Default false
minstring
explanationstring

A description of the variant.

addonsArray of objects(Addons)

Addons that can be selected for the variant.

idstring(uuid)required

A unique identifier for the addon.

namestringrequired

The name of the addon.

priceobject(PriceBreakdown)required

The price of the addon.

currencystringrequired

The currency of the price.

Example: "DKK"
vat_inclusive_centsnumber(int)required

The price in cents including VAT.

Example: 100
vat_amount_centsnumber(int)required

The VAT amount in cents.

Example: 20
vat_exlusive_centsnumber(int)required

The price in cents excluding VAT.

Example: 80
vat_settingobjectrequired
countrystringrequired

The country code for the VAT setting.

Example: "DK"
vat_categorystringrequired

The VAT category for the price.

tax_typestringrequired

The tax type for the price.

Enum"VAT""SALES_TAX""GENERIC"
ratenumber(double)[ 0 .. 0.99 ]required

The VAT rate.

Example: 0.25
exemptbooleanrequired

Indicates if the price is exempt from VAT.

Default false
explanationstring

An explanation or description of the addon.

capacityinteger(int)required

The total capacity of the experience.

tag_idsArray of strings(uuid)required

Array of tag IDs that are associated with the experience.

Tags are used to categorize and filter experiences.

visibilitystringrequired

Describes the visibility of the experience.

If visibility is set to PRIVATE it should not be listed in public places like pages, widgets. Private experiences are used to allow for booking events by hosts them selves, e.g. private tours.

Enum"PUBLIC""PRIVATE"
practical_infostring(MarkdownText)

A descriptive text about the experience.

what_is_includedstring(MarkdownText)

Information about what is included in the experience. In bullet point or numbered format with each point seperated by a new line character.

metadataobject
created_bystring

The user ID of the person who created the experience.

property name*anyadditional property
location_idsArray of stringsnon-empty

All the location IDs where the experience is offered.

capacity_unitSINGLE (object) or GROUP (object)

Indicates unit of an experience.

Depending on the type, the following options are available:

  • SINGLE => Tickets sold individually.
  • GROUP => Tickets sold in a range defined by min_participants and max_participants.
One of:

Indicates unit of an experience.

Depending on the type, the following options are available:

  • SINGLE => Tickets sold individually.
  • GROUP => Tickets sold in a range defined by min_participants and max_participants.
typestringrequired

Tickets sold individually.

Value"SINGLE"
namestring

A custom name for the slot/seat/ticket.

Response
application/json
{
  "is_shared": false,
  "status": "ACTIVE",
  "id": "string",
  "company_id": "string",
  "cutoff": {
    "relative_to": "BEFORE_EVENT_START",
    "duration": "PT2H30M"
  },
  "name": "string",
  "practical_info": "string",
  "what_is_included": "string",
  "metadata": {
    "created_by": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "location_ids": [
    "string"
  ],
  "languages": [
    "en"
  ],
  "media": {
    "primary_image": { … },
    "cover": [ … ]
  },
  "price": {
    "display_variant_id": "9f552162-e05e-4119-83b2-73c1c7bb1466",
    "variants": [ … ]
  },
  "information_requests": [
    { … }
  ],
  "capacity": 0,
  "capacity_unit": {
    "type": "SINGLE",
    "name": "string"
  },
  "tag_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "visibility": "PUBLIC"
}

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