Bubble Action API

openapi: 3.0.3
info:
  title: Bubble Data Action 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: Action
  description: Server-side and client-side action functions invoked by Bubble workflows.
paths:
  /actions/serverSide/{actionName}:
    post:
      tags:
      - Action
      summary: Invoke Server-Side Action
      description: 'Server-side actions are written as `function(properties, context)`.

        They run in a Node.js sandbox, may `require` configured npm

        dependencies, and may return data consumed by subsequent workflow

        steps. Counts as 1 server-side plugin action call (0.2 WU base + per-ms).

        '
      operationId: invokeServerAction
      parameters:
      - name: actionName
        in: path
        required: true
        description: Name of the action as defined in the plugin editor.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                properties:
                  $ref: '#/components/schemas/ActionProperties'
                context:
                  $ref: '#/components/schemas/ServerContext'
      responses:
        '200':
          description: Action returned successfully. Return shape is defined by the plugin's `Returned values` configuration.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /actions/clientSide/{actionName}:
    post:
      tags:
      - Action
      summary: Invoke Client-Side Action
      description: 'Client-side actions are written as `function(properties, context)` and

        run in the browser. Useful for DOM manipulation, calling browser

        APIs, or working with already-loaded data. No workload is incurred

        because no server roundtrip occurs.

        '
      operationId: invokeClientAction
      parameters:
      - name: actionName
        in: path
        required: true
        description: Name of the action as defined in the plugin editor.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                properties:
                  $ref: '#/components/schemas/ActionProperties'
                context:
                  $ref: '#/components/schemas/ClientContext'
      responses:
        '200':
          description: Action returned successfully (or void).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    ServerContext:
      type: object
      description: Server-side context object passed to actions.
      properties:
        currentUser:
          $ref: '#/components/schemas/BubbleThing'
        userTimezone:
          type: string
        keys:
          type: object
          additionalProperties:
            type: string
          description: Plugin shared headers / API keys configured in the editor.
        isBubbleThing:
          type: string
          description: Type-checker function. Returns true if argument is a BubbleThing.
        isBubbleList:
          type: string
          description: Type-checker function. Returns true if argument is a BubbleList.
        getThingById:
          type: string
          description: '`(id) => BubbleThing` — fetch a single record by id.'
        getThingsById:
          type: string
          description: '`(ids) => BubbleList` — fetch multiple records by id.'
    ClientContext:
      type: object
      description: Client-side context passed to actions and element hooks.
      additionalProperties: true
    BubbleThing:
      type: object
      description: Wrapper around a single database record.
      properties:
        id:
          type: string
          description: Read-only unique id (added in v4).
        listProperties:
          type: string
          description: Returns an array of field names defined on the record.
        get:
          type: string
          description: '`(propertyName) => Promise<any>` — returns a Promise resolving to the field value.'
        getAll:
          type: string
          description: '`() => Promise<object>` — returns all fields as an object (added in v4).'
    ActionProperties:
      type: object
      description: Map of property names to values, defined by the plugin author in the editor.
      additionalProperties: true
  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.

        '