openapi: 3.0.3
info:
  title: Bubble Workflow API
  description: |
    The Bubble Workflow API lets external systems trigger backend workflows
    defined in a Bubble app. Each workflow is exposed at a path of the form
    `/api/1.1/wf/{workflow_name}` and may be invoked via POST or GET. Authentication
    requirements are configurable per workflow (none, user/admin, or admin only).
    Workflows can return structured JSON, plain text, custom content, or HTTP
    redirects on success/error.
  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:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: |
        Send the API token in the `Authorization` header as `Bearer <token>`.
        Admin-only workflows require an admin API token. User-restricted
        workflows accept a user token returned from the `Log the User in`
        workflow action.
  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
  schemas:
    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
    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
  responses:
    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'
    Unauthorized:
      description: Missing or invalid bearer token, or token lacks required privileges.
      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'