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

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

List Webhook SubscriptionsPreview

Request

Retrieve all webhook subscriptions for the current organization.

Security
OAuth2
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.

Default 100
curl -i -X GET \
  'https://api.understory.io/v1/webhook-subscriptions?cursor=string&limit=100' \
  -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(WebhookSubscription)
idstringrequired

The unique identifier of the subscription.

urlstringrequired

The URL to send webhook events to.

event_typesArray of stringsrequired

List of event types this subscription is subscribed to.

statestringrequired

The state of the subscription.

Enum"ENABLED""DISABLED"
created_atstring(date-time)required

Timestamp of when the subscription was created.

updated_atstring(date-time)required

Timestamp of when the subscription was last updated.

descriptionstring

A description of the subscription.

metadataobject

Additional metadata for the subscription.

This property lets you add custom data to the subscription. The key has a limit of 40 characters and the value has a limit of 500 characters.

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

Create Webhook SubscriptionPreview

Request

Create a new webhook subscription to receive event notifications at the specified URL.

Security
OAuth2
Bodyapplication/jsonrequired
urlstringrequired

The URL to send webhook events to.

event_typesArray of stringsnon-emptyrequired

List of event types to subscribe to. At least one event type must be specified.

statestringrequired

The state of the subscription.

Default "ENABLED"
Enum"ENABLED""DISABLED"
descriptionstring

A description of the subscription.

metadataobject

Additional metadata for the subscription.

This property lets you add custom data to the subscription. The key has a limit of 40 characters and the value has a limit of 500 characters.

property name*stringadditional property
curl -i -X POST \
  https://api.understory.io/v1/webhook-subscriptions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "string",
    "description": "string",
    "event_types": [
      "string"
    ],
    "state": "ENABLED",
    "metadata": {
      "property1": "string",
      "property2": "string"
    }
  }'

Responses

Subscription successfully created.

Bodyapplication/json
idstringrequired

The unique identifier of the subscription.

urlstringrequired

The URL to send webhook events to.

event_typesArray of stringsrequired

List of event types this subscription is subscribed to.

statestringrequired

The state of the subscription.

Enum"ENABLED""DISABLED"
created_atstring(date-time)required

Timestamp of when the subscription was created.

updated_atstring(date-time)required

Timestamp of when the subscription was last updated.

secretstringrequired

The secret key for verifying webhook signatures.

This value is only returned once when the subscription is created. Store it securely as it cannot be retrieved again.

descriptionstring

A description of the subscription.

metadataobject

Additional metadata for the subscription.

This property lets you add custom data to the subscription. The key has a limit of 40 characters and the value has a limit of 500 characters.

property name*stringadditional property
Response
application/json
{
  "id": "string",
  "url": "string",
  "description": "string",
  "event_types": [
    "string"
  ],
  "state": "ENABLED",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "secret": "string"
}

Get Webhook SubscriptionPreview

Request

Retrieve details of a specific webhook subscription.

Security
OAuth2
Path
subscriptionIdstringrequired

The unique identifier of the subscription.

curl -i -X GET \
  'https://api.understory.io/v1/webhook-subscriptions/{subscriptionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstringrequired

The unique identifier of the subscription.

urlstringrequired

The URL to send webhook events to.

event_typesArray of stringsrequired

List of event types this subscription is subscribed to.

statestringrequired

The state of the subscription.

Enum"ENABLED""DISABLED"
created_atstring(date-time)required

Timestamp of when the subscription was created.

updated_atstring(date-time)required

Timestamp of when the subscription was last updated.

descriptionstring

A description of the subscription.

metadataobject

Additional metadata for the subscription.

This property lets you add custom data to the subscription. The key has a limit of 40 characters and the value has a limit of 500 characters.

property name*stringadditional property
Response
application/json
{
  "id": "string",
  "url": "string",
  "description": "string",
  "event_types": [
    "string"
  ],
  "state": "ENABLED",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}