Bubble Docs
  • Introduction
  • New? Start Here
  • What is Bubble?
  • The Glossary
  • User manual
    • Getting started
      • What is Bubble?
      • Building your first app
        • Planning features
        • Database structure
        • Design and UX
        • eCommerce and payments
          • Shopping cart
          • Checkout page
          • One-time payments
          • Subscriptions
          • Marketplace
      • Creating and managing apps
      • The Bubble editor
        • Tabs and sections
          • Design tab
            • The element tree
            • The property editor
          • Workflow tab
          • Data tab
          • Styles tab
          • Plugins tab
          • Settings tab
            • Application settings
              • Custom headers/body
              • Visual settings
              • Social media sharing
              • Translating your app
              • Email settings
              • Collaboration
            • Custom domain and DNS
          • Logs tab
        • Tools
          • Key features
          • The search tool
          • The Issue Checker
          • The element tree
          • The element property editor
          • The debugger
          • Notes
        • Previewing your app
      • Transitioning to Bubble from...
        • JavaScript
        • HTML and CSS
        • SQL
    • Design
      • Elements
        • The element hierarchy
          • The element tree
        • The page
        • Containers
          • Groups
          • Repeating groups
          • Table elements
          • Popups
          • Floating groups
          • Group focus
        • Visual elements
        • Input forms
          • Text and numbers
          • Dates and time
          • File uploads
          • Selection controls
        • Reusable Elements
      • Styling
        • Color variables
        • Font variables
        • Styles
        • Custom Fonts
      • Responsive design
        • Building responsive pages
        • Legacy articles
          • The Basics (Legacy)
          • Building Responsive Pages (Legacy)
          • Migrating Legacy Pages
          • Tips When Designing (Legacy)
      • Templates
      • The Component Library
      • Importing from Figma
    • Data
      • The database
        • Data types and fields
        • Creating, saving and deleting data
        • Finding data
        • Displaying data
        • Protecting data with privacy rules
        • The database editor
        • Export/import data
          • Exporting data
          • Importing data (CSV)
        • Working with location data
        • Using Algolia
        • Database structure by app type
          • Marketplace Apps
          • Directory & Listings Apps
          • Social Network Apps
          • SaaS Apps
          • Project Management Apps
          • CRM Apps
          • Professional Services Apps
          • On-demand Apps
          • Documentation/ CMS Apps
          • Applicant Tracking System (ATS) Apps
          • Portfolio Apps
          • Gallery Apps
          • Online Store / Ecommerce Apps
          • Blog Apps
          • Messaging App
          • Dashboards
          • Building Block Apps
          • Bubble as a backend
      • Files
      • Images
      • Static data
        • App texts (translations)
        • Option sets
      • Temporary data
        • Custom states
        • URL parameters
      • User accounts
        • Authentication plugins
          • Facebook plugin
          • Fitbit plugin
          • Google plugin
          • Instagram plugin
          • LinkedIn plugin
          • Pinterest plugin
          • Slack plugin
          • Wistia plugin
          • YouTube plugin
        • Cookies set by Bubble
      • Time, dates and time zones
    • Logic
      • The frontend and backend
      • Workflows
        • Events
          • Frontend events
            • Recurring workflows
            • Custom events
          • Backend events
            • Database trigger events
        • Actions
        • API Workflows
      • Dynamic expressions
      • Conditions
      • Navigation
        • Single-page applications (SPA)
        • Multi-page applications
        • Page slugs
    • Workload
      • Understanding workload
        • Activity types
        • The workload calculation
        • Client-side and server-side processing
      • Tracking workload
        • Measuring
          • Using App Metrics
        • Monitoring
          • Workload notifications
          • Infinite recursion protection
      • Optimizing workload
        • Optimization framework
        • Optimization checklist
          • Page load
          • Searches
          • Workflows and actions
          • Backend workflows
        • Agency showcases
          • Minimum Studio
          • Neam
          • Support Dept
    • Security
      • Bubble's security features
      • Planning app security
      • Client-side and server-side
      • Bubble account security
      • App security
      • Page security
      • Database security
      • API security
        • API Connector security
        • Data API security
        • Workflow API security
      • Flusk
        • Overview
        • Flusk plan features
        • Getting started with Flusk
        • Flusk security tools
          • The Issues Explorer
          • Issue details
          • Tools and settings
            • Pages rating
            • Database rating
        • Flusk FAQ
      • Cookies
      • Security checklist
    • Publishing your app
      • Web app
      • Native mobile app
        • Global native mobile settings
        • iOS App Store
        • Google Play Store
        • Publishing FAQ
    • AI
      • Generate apps with AI
        • About AI app generation
      • AI page designer
      • Connect to AI agents
    • Maintenance
      • Collaborators
      • Version control
        • Best practices: Version control
        • Transitioning from the legacy version control
        • Terminology: Version control
        • Version Control (legacy)
      • Commenting
      • Database maintenance
        • Copying the database
        • Restoring database backups
        • Bulk operations
          • Bulk operation methods compared
        • Wiping change history
      • Performance
        • Hard limits
        • Capacity Usage (legacy)
        • Notes on queries
      • SEO
        • Introduction to SEO
        • SEO: App
        • SEO: Page
      • Testing and debugging
        • Introduction to testing and debugging
        • The debugger
        • The server logs
        • Supported browsers
      • API workflow scheduler
    • Integrations
      • API
        • Introduction to APIs
          • What is a RESTful API?
        • The Bubble API
          • Bubble API terminology
          • Authentication
            • How to authenticate
            • No authentication
            • As a User
            • As an admin
          • The Data API
            • Data API Privacy Rules
            • Data API endpoints
            • Data API requests
          • The Workflow API
            • Workflow API privacy rules
            • Workflow API endpoints
            • API workflows
              • Creating API workflows
              • Scheduling API workflows
              • Recursive API workflows
              • API Workflow Scheduler
              • Case: Stripe notifications
        • The API Connector
          • Authentication
          • API Connector security
          • API guides
            • OpenAI
              • Authentication
              • Calls
                • ChatGPT
                  • Chat
            • Google Translate
              • How to setup Google API keys
          • Streaming API
        • API security
        • Plugins that connect to APIs
        • API Glossary
      • Plugins
        • What Plugins Can Do
        • Installing and using Plugins
        • Authentication plugins
        • Special Plugins
      • SQL Database Connector
      • Bubble App Connector
      • WorkOS
        • WorkOS SSO
        • WorkOS API
    • Infrastructure
      • Sub-apps
      • Bubble release tiers
      • Hosting and scaling
        • How Bubble hosting works
        • Scaling with Bubble
        • CDN (Cloudflare)
        • Bubble app names
        • Domain and DNS
      • Compliance
        • GDPR
        • SOC 2 Type II
        • HIPAA
        • Other frameworks and standards
    • Bubble for Enterprise
      • Hosting and infrastructure
        • Dedicated instance
          • The Dedicated editor experience
          • Technical specs
          • Main cluster dependencies
          • Customizable options
          • Migration process
            • Pre-migration
            • During migration
            • Post-migration
      • Security and compliance
        • Single sign-on (SSO)
        • GDPR
        • SOC 2 Type II
        • HIPAA
        • Other frameworks
        • Bubble's security features
      • Admin and collaboration
      • Priority support
      • Billing and Payment Guideline for Dedicated Instances
  • Core Reference
    • Using the core reference
    • Bubble's Interface
      • Design tab
      • Design tab (Legacy)
      • Workflow tab
      • Data tab
      • Styles tab
      • Styles tab (Legacy)
      • Plugins tab
      • Settings tab
      • Logs tab
      • Template tab
      • Toolbar
      • Top and context menu options
      • Deployment and version control
        • Deployment & Version Control Dropdown (legacy)
      • Notes
    • Elements
      • General properties
      • General properties (Legacy)
      • Styling properties
      • Styling Properties (Legacy)
      • Responsive Properties
      • Responsive Properties (Legacy)
      • Conditional formatting
      • States
      • Page Element
        • Page Element (Legacy)
      • Visual Elements
      • Containers
      • Container Layout Types
      • Containers (Legacy)
      • Input Forms
      • Reusable Elements
      • Element Templates (legacy)
    • Workflows
    • Events
      • General events
      • Element events
      • Custom events
      • Recurring event
      • Database trigger event
    • Actions
      • Account
      • Navigation
      • Data (things)
      • Email
      • Element
      • Custom
    • Data
      • Data Sources
      • Operators and comparisons
      • Search
      • Privacy
    • Styles
    • API
      • The Bubble API
        • The Data API
          • Authentication
          • Data API endpoints
          • Data API requests
        • The Workflow API
      • The API Connector
        • Authentication
        • Adding calls
    • Bubble-made Plugins
      • AddtoAny Share Buttons
      • Airtable
      • API Connector
      • Blockspring
      • Box
      • Braintree
      • Bubble App Connector
      • Chart.js
      • Circle Music Player
      • Draggable Elements
      • Dropzone
      • Facebook
      • Fitbit
      • Full Calendar
      • Google
      • Google Analytics
      • Google Optimize
      • Google Places
      • Ionic Elements
      • iTunes
      • Slidebar Menu
      • LinkedIn
      • Localize Translation
      • Mixpanel
      • Mouse & Keyboard Interactions
      • Multiselect Dropdown
      • Progress Bar
      • Rich Text Editor
      • Rich Text Editor (Legacy)
      • Screenshotlayer
      • SelectPDF
      • Slack
      • Segment
      • Slick Slideshow
      • SQL Database Connector
      • Star Rating
      • Stripe
      • Tinder-like Element
      • Twitter
      • YouTube
      • Zapier
    • Application Settings
      • App plan
      • General
      • Domain / email
      • Languages
      • SEO / metatags
      • API
      • Collaboration
      • Sub-apps
      • Versions
  • Account & Marketplace
    • Account and billing
      • Pricing and plans
        • Plans and billing
        • Billing cycle
        • FAQ: Pricing and Workload
      • Account Management
      • Building Apps for Others
      • Selling on the Marketplace
      • Plans & Billing (legacy)
    • Official Bubble Certification
      • Hiring certified developers
    • Building Plugins
      • The Plugin Editor
      • General Settings
      • Updating to Plugin API v4
      • Adding API Connections
      • Building Elements
      • Building Actions
      • Loading Data
      • Publishing and versioning
      • Github Integration
    • Building Templates
    • Application and data ownership
    • Marketplace policies
    • Bug reports
  • Vulnerability Disclosure Policy
  • Beta features
    • About the Beta features section
    • Native mobile apps 🔒
      • Introduction
        • What is a native mobile app?
        • Native mobile vs. web development
        • Differences in native and web elements
        • Native mobile app terminology
      • Building
        • Views and navigation
        • Native mobile actions
        • Components and gestures
        • Device resources
          • Location services
          • Camera/photo library
      • Previewing
      • Publishing
Powered by GitBook
On this page
  • The endpoint
  • Naming your workflows
  • Constructing the endpoint
  • Labelling your workflows
  • Exposing the workflow externally
  • Overriding authentication
  • Defining the HTTP method
  • Defining parameters
  • Manual definition
  • Automatic detection
  • Overriding timezones
  • Returning data from the API Workflow

Was this helpful?

  1. User manual
  2. Integrations
  3. API
  4. The Bubble API
  5. The Workflow API
  6. API workflows

Creating API workflows

This section covers how to create and setup an API Workflow.

Last updated 11 months ago

Was this helpful?

Creating an API Workflow works in the same way as creating regular workflows in on a page. After and you click Click here to add a backend workflow and choose New API workflow.

The endpoint

For each API workflow that you create and expose a unique endpoint is created, consisting of your app's Worfklow API root URL and the name that you give the workflow.

Naming your workflows

The complete API Workflow endpoint is constructed by combining the root URL with the name. As a consequence, the name of the API needs to be in a URL-friendly format:

  • each API Workflow needs to have a unique name

  • use lowercase letters

  • remove spaces and special characters (replacing them with dashes or underscores)

  • remove any trailing or leading white space

  • don't make the name too long

For example, instead of naming a workflow Create New User, you would name it create-new-user.

Constructing the endpoint

Having activated the Workflow API and given our workflow a name, we can now construct the complete endpoint:

https://my-bubble-application.bubbleapps.io/version-test/api/1.1/wf/create-new-user

Labelling your workflows

While the name of the workflow needs to be URL friendly, you are still free to provide a more humanly readable label for it. The API Workflow will automatically inherit its label from the name, but you can change this label as you see fit to make it easier to read and search for.

Exposing the workflow externally

Having created and named our Workflow, we need to make sure that it is exposed outside of your application, or the endpoint will simply return an error.

Check the Expose as public API workflow box to give external applications access to the endpoint.

Only expose API Workflows that you intend to trigger from an external system. If you will only use the workflow as part of your own app's internal processes, keep the box unchecked.

Overriding authentication

Just like the Data API, API Workflows require that the themselves before the workflow will trigger.

To set up an API Workflow to be accessible by anyone, check the This workflow can be run without authentication checkbox. Keep in mind that Privacy Rules can still limit the functionality of the API Workflow.

Be cautious when opening up API Workflows to be accessible without authentication as this will allow anyone to trigger the workflow at any time.

Defining the HTTP method

The determines what kind of action the client instructs the server to perform. By default, API Workflows use the POST HTTP method, but some external systems require the ability to use the GET method for . To switch between the two, click the Trigger workflow with dropdown.

If you select to trigger the API Workflow with a GET request, the parameter definition will default to Manual Definition, and the field will be hidden. You can still define key-value pairs as normal.

If you are using API workflows via the App Connector, these workflows will automatically be triggered by the proper HTTP request defined in “Trigger workflow with” dropdown.

When you switch between GET and POST, the definitions and parameters you’ve defined will be preserved. The contents for Detect request data will be saved if you decide to switch between the different options of Parameter Definition. The Bubble issue checker will ensure the data is correctly formatted

Defining parameters

In many cases an API Workflow will need some parameters to run. Let's say for example that you the workflow is set up to create a new User in your app, you will need to include key information like email and perhaps a first and last name. Using parameters you can send this information to the workflow from outside of Bubble.

You have two ways to define parameters:

  • define the structure yourself

  • automatically detect the structure of the received data

The first option is better for an API workflow you define and when you control how the request is made (for instance when you use scheduled workflows, or build a custom client), while the second option is useful when using the API workflow's endpoint as a response to a webhook.

Manual definition

Adding a parameter goes through three steps:

  1. Give the parameter a name

  2. Pick the type of data you will receive

  3. Specify whether the parameter is optional or not

Both the type of data and optionality are important settings: Bubble will validate the data when a request is made and if a parameter is sent with the wrong formatting or a non-optional parameter is missing, Bubble will return an error.

In the example above we have include three parameters of type text to create a User:

  1. Email (required)

  2. First name (required)

  3. Last name (required)

  4. Nickname (optional)

Automatic detection

Bubble can also automatically detect the parameters that are sent by an external service (webhook). It does this by "listening" for the incoming request and checking the parameters that are sent in the call – that way it can identify each one and attempt to determine what kind of data type it is.

To do this, you need to make a small amendment in the endpoint URL to let Bubble know that this is an initialization call.

To automatically detect data, do the following:

  1. In the API Workflow inspector window, set Parameter definition to Detect request data

  2. Click Detect data

  3. Bubble will reveal the initialization URL

  4. Send the request from the external system

Initialization URL

Bubble will show you the URL you need to send the request to, but you can also construct this by yourself:

https://appname.bubbleapps.io/version-test/api/1.1/wf/endpoint/initialize

or

https://yourdomain.com/version-test/api/1.1/wf/endpoint/initialize

The request should be made to the test version of your app, as it's the version you're modifying. You never need to send an initialization to the live version, as any changes you make to the parameters need to be deployed.

Overriding timezones

Overriding timezones in the backend requires that you activate the advanced setting Enable timezone override controls in your app's general settings.

API workflows allow you to override the time zone of the request by setting an alternative timezone with a static or dynamic choice. This helps you standardize the way in which your app parses and stores data. For example:

  • if you parse 1/1/2000 from Eastern Time and keep the default setting, Bubble will save that date as 1/1/2000 12:00 AM Eastern Time

  • If you instead override the client timezone with Pacific Time, selecting 1/1/2000 will save 1/1/2000 12:00 AM Pacific Time

This type of timezone standardization is useful in different scenarios:

  • Where an external API request includes a timestamp, but not a timezone: you can set a static or dynamic timezone when that call is received to ensure its properly parsed

  • Apps that deal with scheduling where the timezone of the scheduled appointment needs to remain constant: for example, if a user books a conference in London from Tokyo, your app can ensure that the timezone used is indeed London and not Tokyo.

Returning data from the API Workflow

Sometimes you'll want your app to return data after a workflow has been triggered. In most cases, to respond with data from your database you will want to use the , but sometimes you need more control over what data you send back, such as:

  • verifying that a workflow completed successfully

  • returning data that depends on the workflow

  • combining data/fields from multiple data types

To return data you can use the Return data from API action:

In the example above, we have a database Thing where we save a score. Let's imagine that we want to return the average score of all Things in the database. We can use the Return data from API feature to perform a search and return the updated average that depends on Step 1.

The root URL is made visible in the Bubble editor as soon as you as illustrated below:

Reference:

Our webinar gives an introduction to how API workflows work
activate the Workflow API
activating the Workflow API
accessing the backend editor
Application settings: Advanced
Click New API Workflow to create.
Activating the Workflow API in Bubble's API Settings. exposes the root URL of your API workflows.
Giving your API Workflow a different label makes it easier to work with and search for.
To be reachable from outside of your own app, this box needs to be checked.
Bubble can automatically detect the parameters in your call by using the Detect data feature.