Skip to content

Get experience
Alpha

Request

Get an experience by its ID.

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

The unique identifier of the experience.

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
GET
/v1/experiences/{experienceId}
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 of the experience.

statestringrequired

The lifecycle state of the experience.

  • ACTIVE — bookable; the default operational state.
  • INACTIVE — temporarily not bookable, but still managed by the company. Can transition back to ACTIVE.
  • ARCHIVED — terminal state. The experience is hidden from active management; it is no longer bookable and cannot transition back.
  • DELETED — terminal state. The experience has been deleted; it is no longer bookable and cannot transition back.
  • UNKNOWN — defensive default; should not appear on a correctly configured experience.
Enum:"ACTIVE""INACTIVE""ARCHIVED""DELETED""UNKNOWN"
namestringrequired

The display name of the experience, returned in the language negotiated via the Accept-Language header.

created_atstring, (date-time)required

Timestamp of when the experience was created.

updated_atstring, (date-time)required

Timestamp of when the experience was last modified.

Includes both content edits and lifecycle transitions (state changes, archival, deletion).

descriptionstring(MarkdownText)

A long-form description of the experience, returned in the language negotiated via the Accept-Language header.

The string may contain Markdown formatting; clients should render it accordingly.

tag_idsArray of strings

Opaque tag identifiers associated with the experience.

Use them to group or filter experiences in your own UI; the IDs are not resolved to tag entities by this API.

mediaArray of any(Media)

Media items (images and videos) attached to the experience, ordered as configured by the company.

metadataobject(Metadata)

Free-form key-value pairs attached by the integrator. Both keys and values are strings; the API does not enforce schema, length, or content.

Example:
{
  "key1": "value1",
  "key2": "value2"
}
Response
{
  "id": "string",
  "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"
  }
}