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. See Production and the full API.
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, 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 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.bubbl.tech/platform/v1/me \
  -H "Authorization: Bearer $BUBBL_API_TOKEN"

JAVASCRIPT

const response = await fetch('https://api.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.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": "production",
    "abilities": ["campaigns:read", "locations:read", "locations:write"],
    "platform_api_enabled": true
  }
}

platform_api_enabled is false until Bubbl turns on the full API for your workspace. Until then, only GET /me and the reports work.

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.