Bubble Workflow API

openapi: 3.0.3
info:
  title: Bubble Data Action Workflow API
  description: 'The Bubble Data API exposes the database of a Bubble app as a REST interface.

    External systems can read, search, create, modify, replace, and delete records

    of any data type defined in a Bubble app, with optional pagination, sorting,

    and search constraints. Authentication uses bearer tokens (admin API tokens

    bypass privacy rules; user tokens enforce them). Endpoints exist for live and

    development (`version-test`) environments.

    '
  version: '1.1'
  contact:
    name: Bubble Support
    url: https://bubble.io/contact
  license:
    name: Bubble Terms of Service
    url: https://bubble.io/legal/terms-of-service
servers:
- url: https://{appname}.bubbleapps.io/api/1.1
  description: Live App on Bubble subdomain
  variables:
    appname:
      default: myapp
      description: Bubble app name
- url: https://{appname}.bubbleapps.io/version-test/api/1.1
  description: Development (version-test) on Bubble subdomain
  variables:
    appname:
      default: myapp
      description: Bubble app name
- url: https://{customDomain}/api/1.1
  description: Live App on a custom domain
  variables:
    customDomain:
      default: example.com
      description: Custom domain pointing to the Bubble app
security:
- BearerAuth: []
tags:
- name: Workflow
  description: Trigger backend (server-side) workflows defined in the Bubble app.
paths:
  /wf/{workflow_name}/initialize:
    parameters:
    - $ref: '#/components/parameters/WorkflowName'
    post:
      tags:
      - Workflow
      summary: Initialize Workflow
      description: 'One-time call used while building a workflow. Bubble inspects the

        request body and headers and uses them to detect the parameter

        contract for subsequent calls. Disable detection before going live.

        '
      operationId: initializeWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowParameters'
      responses:
        '200':
          description: Detection succeeded; the workflow's parameter contract is now defined.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '400':
          $ref: '#/components/responses/BadRequest'
  /wf/{workflow_name}:
    parameters:
    - $ref: '#/components/parameters/WorkflowName'
    post:
      tags:
      - Workflow
      summary: Trigger Workflow
      description: 'Invoke the workflow with the parameters defined in the editor. Body

        parameters are sent as JSON unless the workflow is configured to

        accept query-string parameters.

        '
      operationId: triggerWorkflow
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowParameters'
      responses:
        '200':
          description: Workflow executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
            text/plain:
              schema:
                type: string
        '301':
          description: 'Redirect to a configured success or error URL. The query string

            includes the response payload or `statusCode`/`message` on error.

            '
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    get:
      tags:
      - Workflow
      summary: Trigger Workflow Via GET
      description: 'Invoke the workflow with parameters supplied via the query string.

        GET-mode workflows must be explicitly enabled in the Bubble editor.

        '
      operationId: triggerWorkflowGet
      responses:
        '200':
          description: Workflow executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
            text/plain:
              schema:
                type: string
        '301':
          description: Redirect to configured success/error URL.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    Unauthorized:
      description: Missing or invalid bearer token, or token lacks required privileges.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: 'Invalid parameters, validation failure, or unmet conditions. Workflows

        configured for webhook compatibility may return 200 instead of 400.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests. The plan-level requests-per-minute limit has been exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    WorkflowResponse:
      type: object
      description: 'Default JSON response. Workflows can also return plain text or a

        custom content-type configured via the `Return data from API` action.

        '
      properties:
        status:
          type: string
          example: success
        response:
          type: object
          additionalProperties: true
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        body:
          type: object
          properties:
            status:
              type: string
            message:
              type: string
    WorkflowParameters:
      type: object
      description: 'Parameter map. Field names and types are defined per workflow in the

        Bubble editor or auto-detected via the `/initialize` call.

        '
      additionalProperties: true
  parameters:
    WorkflowName:
      name: workflow_name
      in: path
      required: true
      description: 'Name of the API workflow as defined in the Bubble editor. Slugs are

        case-sensitive and must match the workflow exactly.

        '
      schema:
        type: string
      example: register_user
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: 'Send the API token in the `Authorization` header as `Bearer <token>`.

        Admin tokens bypass privacy rules; user tokens (returned by the

        `Log the User in` workflow action) enforce privacy rules per user.

        '