Skip to content

Getting started

This takes about five minutes once you have a key.

1. Get a key

Ask your Speakeasy contact for a key. Tell them which venues you need and what you want to build, so they can turn on the right routes. Two kinds of key explains the difference.

Keep the key on your server. Never put it in a web page, a mobile app, a URL or a log.

2. Pick an environment

Environment Base URL Use it for
Production https://production.speakeasygo.com Real venues and real guests
Test https://preprod.speakeasygo.com Trying things out with test data

A key works in one environment only, so ask for a test key too. Data in the test environment can change at any time.

All answers are plain JSON over HTTPS.

3. Make your first call

Send your key in the token header. This lists the first venue your key can read.

curl "https://preprod.speakeasygo.com/external/v1/venues?take=1" \
  -H "token: $SPEAKEASY_TOKEN"

import os
import requests

answer = requests.get(
    "https://preprod.speakeasygo.com/external/v1/venues",
    params={"take": 1},
    headers={"token": os.environ["SPEAKEASY_TOKEN"]},
    timeout=30,
)
answer.raise_for_status()
print(answer.json())

const answer = await fetch(
  "https://preprod.speakeasygo.com/external/v1/venues?take=1",
  { headers: { token: process.env.SPEAKEASY_TOKEN } },
);
if (!answer.ok) throw new Error(`Speakeasy answered ${answer.status}`);
console.log(await answer.json());

You get something like this:

{
  "list": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "url": "https://speakeasygo.com/sample-bar?vid=VN-abc123",
      "name": "Sample Bar",
      "timezone": "America/New_York"
    }
  ],
  "total": 1,
  "count": 1,
  "hasMany": false,
  "nextCursor": null,
  "generatedAt": "2026-11-05T12:00:00.000Z"
}

Your integration may see more fields than this. See What your key can reach.

With a venue key

A venue key works on the /partners/ routes. This lists upcoming public events for your venue.

curl "https://preprod.speakeasygo.com/partners/events?take=1&version=PUBLISHED&status=ENABLED&eventStatus=APPROVED&timeVersion=UPCOMING" \
  -H "token: $SPEAKEASY_VENUE_TOKEN" \
  -H "timezone: America/New_York"

If it does not work

You see What it means
401 from /external/v1 The key is missing or not valid here. Check it is the key for this environment.
400 "Token is required" or "Unable to validate token" from /partners The same thing on the venue routes. They answer 400 instead of 401.
403 "Missing venues:read capability" Your integration does not have this route yet. Ask your contact to add it.
403 "... is not provisioned" Your integration does not have this filter or sort yet.
200 with an empty list The call worked, and nothing matches. Your key may not cover any venue yet.

Every answer from /external/v1 carries an X-Request-Id header. Send it to us when you report a problem.

Next