Platform API overview

Connect Bubbl to your own systems and to tools like Zapier, Make and n8n. Manage campaigns, notifications and locations and read your reports with a token over HTTPS.

The Platform API is a REST API for your servers, scripts and automation tools. Use it to keep Bubbl in step with the systems you already run: create locations from your store list, set up campaigns from your own tools, or pull results into a spreadsheet or data warehouse.

It's separate from the Bubbl SDK. The SDK talks to Bubbl from your app on each phone; the Platform API is for your back office. Never put a Platform API token in a mobile app or a web page.

What's in the API#

Area	What you can do	Abilities
Campaigns	List, get, create, update and delete campaigns; publish and pause them	`campaigns:read`, `campaigns:write`
Notifications	List, get, create, update and remove a campaign's notifications	`notifications:read`, `notifications:write`
Locations	List, get, rename and delete locations; create and update them in bulk from GeoJSON	`locations:read`, `locations:write`
Media	Coming soon: view, upload and delete media	`media:read`, `media:write`
Reports	Read the summary and the campaign, location, notification and survey reports for any date range	`reports:read`

Media doesn't have endpoints yet. You can already give a token its abilities, so it's ready when they arrive.

Each token is given the abilities it needs when you create it. See Authentication.

What isn't in the API#

Company settings, the team and users, billing, push credentials and SDK keys aren't in the Platform API. You manage them in the dashboard.

How requests work#

Base URL: https://api.bubbl.tech/platform/v1 for Production and https://api.sandbox.bubbl.tech/platform/v1 for the Sandbox. See Sandbox and Production.
Auth: every request sends a token as Authorization: Bearer bubbl_….
JSON: request bodies and responses are JSON. Send Content-Type: application/json with a body.
Names and values: fields are snake_case, times are ISO 8601 in UTC (2026-09-28T09:15:02+00:00) and ids are UUIDs.
Responses: a single item comes back as {"data": {…}}. A list comes back as {"data": […], "meta": {"next_cursor": …}}. See Pagination and syncing.
Errors: every error has the same shape, {"error": {"code", "message", "fields"}}. See Errors.

Make your first call#

1
Create a token
In the dashboard, open Configuration › Platform API in your Sandbox, click Create token, give it a name and at least one ability, and copy the token. It's shown once.

Call /me

GET /me tells you which workspace the token belongs to, whether it's the Sandbox or Production, and what the token can do. It needs no ability, so it's the quickest way to check a token works.

CURL

curl https://api.sandbox.bubbl.tech/platform/v1/me \
  -H "Authorization: Bearer $BUBBL_API_TOKEN"

JAVASCRIPT

const response = await fetch('https://api.sandbox.bubbl.tech/platform/v1/me', {
  headers: { Authorization: `Bearer ${process.env.BUBBL_API_TOKEN}` },
});
const { data } = await response.json();
console.log(data.environment, data.abilities);

PYTHON

import os
import requests

response = requests.get(
    "https://api.sandbox.bubbl.tech/platform/v1/me",
    headers={"Authorization": f"Bearer {os.environ['BUBBL_API_TOKEN']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json()["data"])

A successful response looks like this:

RESPONSE

{
  "data": {
    "workspace": { "id": "01926f3a-5b10-7c44-8e21-6d3f0a9b1c2d", "name": "Acme Coffee" },
    "environment": "sandbox",
    "abilities": ["campaigns:read", "locations:read", "locations:write"],
    "platform_api_enabled": true
  }
}

platform_api_enabled is always true in the Sandbox. In Production it's false until Bubbl turns on the full API for your workspace. Until then, only GET /me and the reports work there.

Next steps#

Authentication: abilities, expiry and revoking tokens.
Campaigns and notifications: create a campaign, add a notification and publish it.
Reports: pull your campaigns' results into your own tools.
Rate limits: how many requests you can make.
Importing locations with GeoJSON: load your locations in one call.
Using Bubbl with Zapier: connect Bubbl without writing code.

The API reference in the sidebar lists every endpoint with its fields.

Was this page helpful?