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 guides and general information, go to the Documentation.

How the API works

Base URL: https://api.understory.io. Every path starts with a major version, for example /v1/bookings.
Authentication: OAuth2.0 bearer tokens from https://api.auth.understory.io/oauth2/token. Internal integrations use the client credentials grant, third-party integrations the authorization code grant. See Authentication.
Access tokens: cache the access token and reuse it on every request until shortly before expires_in runs out. Do not request a token per API call.
Pagination: list endpoints take cursor and limit and return items and next. See Pagination.
Errors: failed requests return a JSON body with a code and a message. See Errors.
Rate limits: on 429 Too Many Requests, back off before retrying. See Rate limits.
Dates and times: instants carry a UTC offset; session times are local to the experience's location. See Dates and times.
Changes: new fields and new values of extensible enums are added without a new version. See Breaking changes.

Preview and Alpha

Some parts of the Understory API are still under active development.

Refer to API Versioning for details on what you can expect from endpoints and webhooks marked with Preview and Alpha.

Questions or feedback? Use the chat in the bottom-right corner of this site. We’d love to hear your thoughts!

Download OpenAPI description

index.json

index.yaml

Overview

URL

https://developer.understory.io

License

Apache 2.0

Languages

Servers

https://api.understory.io