Skip to main content

Getting started

Get started with the Surreal API.
NOTE: As stated in the Surreal API usage agreement, a backlink to surreal.live or another agreed surreal url must accompany any public facing use of this data.

What you'll need​

  • A Surreal account with access to venue(s) or venue group(s).
  • Events and/or performances at the venue(s) or group(s) you have access to.

Generate a new API Key​

Get your Surreal Bearer Token​

Log into the Surreal app and copy your access token from the browser.

How?​

Once you have Surreal open in your broswer:

Chrome:
  -> Right click 
  -> inspect 
  -> Application tab 
  -> Cookies 
  -> https://app.surreal.live for prod, or https://app.staging.surreal.live for staging 
  -> copy the value of the access_token. It should start with 'ey'
  
Firefox: 
  -> Right click 
  -> inspect 
  -> Storage tab 
  -> Cookies 
  -> https://app.surreal.live for prod, or https://app.staging.surreal.live for staging 
  -> copy the value of the access_token. It should start with 'ey'

Call the Create Events API key endpoint​

This is the bearer token you need to create a Surreal API key.
NOTE: This bearer token is for any other API annotated as using surrealBearerAuth.

This token should be added into the authorization header with a Bearer prefix like the following when calling the

# HTTP request auth header
"authorization": "Bearer <ACCESS_TOKEN_VALUE>"

Assuming you have permission to create the key, your response payload should look like the following

{

    "key": "evt_3ZbRu1bfEPFaqd29w8fK8uUu",
    "keyId": "key_3qD8vo2yzsvpRuBWsHqtgS5Absa"

}

The key value should now be used in place of the access_token_value in all subsequent calls to read data from the Surreal Events API. NOTE: This API Key is to be used for any other annotated as using eventsApiKeyAuth.

# HTTP request auth header
"authorization": "Bearer <API_KEY_VALUE>"

Events API Reference

Rate Limits​

There is API rate limiting in place. Each key will be able to make 7500 requests per day, with no more than 30 in any 1 minute window.

API URL's​

API Urls can be found by clicking the URL path in the API reference, this will show a dropdown for each environment. Note that generally any POST/PUT/DELETE point to a write URL, and any GET point to a read replica URL.