Quickstart

This guide takes you from zero to your first authenticated API call in three steps. You’ll create an API key, point it at the Bubbles API, and confirm it works by fetching your own account.

1. Create an API key

The easiest way to get a token is from the Bubbles app:

1. In Bubbles, open Settings → API keys.
2. Click Create key, give it a name (for example, quickstart), and copy the token. It looks like bbls_pat_… and is shown only once — store it somewhere safe.

Note

Creating a key requires a workspace with paid-feature access (otherwise the API returns 403 pro_plan_required). You can hold up to 10 active keys. Prefer to automate key creation, or building a third-party app for other users? See Authentication for the session-based create/revoke endpoints and the full OAuth 2.1 flow.

2. Set your base URL and token

The Bubbles API is served under a /v1 prefix at your Bubbles API host. Set two shell variables so you can copy-paste every example on this site:

export BASE_URL="https://api-tom.usebubbles.com"   # your Bubbles API origin
export BUBBLES_TOKEN="bbls_pat_…"                       # the key you just created

Tip

BASE_URL is the origin of the API you’re calling (scheme + host, no trailing slash) — set it to your Bubbles API host. Nothing on this site hardcodes a host, so every example works against whichever origin you set.

3. Make your first call

Fetch the account the token belongs to. A 200 with your id and email means you’re connected:

GET /v1/me — confirm your token works

curl "https://api-tom.usebubbles.com/v1/me" \
  -H "Authorization: Bearer $BUBBLES_TOKEN"

{
  "id": "be0c0582-afce-446d-aa21-1d3e7856137a",
  "email": "you@example.com",
  "name": "Ada Lovelace",
  "picture_url": null
}

If you get 401 unauthorized, double-check the Authorization: Bearer header and that the token was copied in full. If you get token_revoked, the key was revoked — create a new one.

Next steps

You’re authenticated. From here:

• List your bubbles — GET /v1/bubbles returns your meetings, recordings, and images. See the API Reference.
• Read a transcript — GET /v1/bubbles/{id}/transcript.
• Get notified — subscribe to events with Webhooks.
• Connect an AI agent — add Bubbles to Claude or ChatGPT over MCP.