Production and the full API

The Platform API has one address, and your tokens work on it straight away for reports. Everything else is switched on for your workspace by Bubbl, and your plan's limits apply to what the API creates.

The base URL#

There is one address for the Platform API:

https://api.bubbl.tech/platform/v1

Your workspace is the one you see in the dashboard. Tokens belong to it, and everything the API creates is live as soon as it's active. There's no separate test workspace to build in first.

Create a token#

Open Configuration › Platform API in the dashboard, click Create token, give it a name and the abilities it needs, and copy the token. It's shown once. See Authentication for abilities, expiry and revoking.

You can create a token with any ability straight away. What it can do depends on whether Bubbl has turned on the full API for your workspace.

Reports and the full API#

The full API is switched on for each workspace by Bubbl. It isn't part of any plan. Until it's on, any request that needs an ability other than reports:read gets 403 with the code platform_api_not_enabled, whatever abilities the token has:

{
  "error": {
    "code": "platform_api_not_enabled",
    "message": "The full Platform API isn't enabled for this workspace yet. Contact customer services to turn it on; reporting is available now."
  }
}

Once it's on, the same tokens work without any change. If it's ever turned off again, your tokens are kept, but only GET /me and the reports work until it's back on.

Ask for the full API#

Open Configuration › Platform API and click Contact us. Bubbl turns the full API on for your workspace.

To check from code, call GET /me. It returns platform_api_enabled, which is false until the full API is on.

Plan limits apply#

The API follows the same plan limits as the dashboard. On the Free plan that's 3 campaigns, 3 locations, 3 notifications and 2 team members. Campaigns, locations and notifications all count, whether or not they're active. Team members can't be managed through the API, so that limit only matters in the dashboard.

What happens at a limit depends on what you're creating:

• Campaigns and notifications: a request that would go over the limit is refused with 403 and the code limit_exceeded. Nothing is created. The same code comes back when a campaign already has as many notifications as your plan allows.
• Locations: locations are created by importing them, and location import needs a paid plan. On the Free plan an import is refused with 403 and the code feature_not_in_plan, so create locations in the dashboard instead. On a plan with a location limit, an import isn't refused when it reaches the limit: new locations past it are skipped, and each one says so in the import's results.

{
  "error": {
    "code": "limit_exceeded",
    "message": "You've reached the limit for max_campaigns.",
    "fields": {
      "max_campaigns": ["Limit is 3, already at 3."]
    }
  }
}

The name in fields is the limit that was hit: max_campaigns or max_notification_templates, or max_campaign_attachments for the notifications on one campaign. Everything you've already created keeps running. To create more, remove something or upgrade your plan. See Errors.

Surveys, audio and video aren't on the Free plan either, so a request to create one is refused with a 422 and the code validation_failed, naming the field.

Reports need the Reports feature in your plan. Every plan includes it today, Free too. If a workspace's plan doesn't, reports:read requests are refused with 403 and the code feature_not_in_plan. See Errors.

A workspace scheduled for deletion#

While a workspace is scheduled for deletion, its tokens are refused with 403 and the code workspace_paused.

Testing without a Sandbox#

Bubbl doesn't have a Sandbox on production today, so what you create is real. These are suggestions to keep a first integration safe:

• Start with a token that only has reports:read. It can't change anything.
• A new campaign isn't paused, so pause it straight away after you create it, and publish it when you're ready. See Campaigns and notifications.
• Use a few small test locations rather than your whole store list.
• On a paid plan, use the dry run on location imports to see what would happen before anything is created.
• Keep one token per integration, so you can revoke a test token without touching the others.