Bubble Action API

openapi: 3.2.0
info:
  title: Bubble Plugin Action API
  description: 'The Bubble Plugin API is a JavaScript SDK surface (not an HTTP API) that plugin

    authors use to extend Bubble apps. It exposes server-side actions, client-side

    actions, and visual elements that read configured properties and interact with

    the runtime via a `context` object. Plugin API v4 replaces Fibers with

    Promises and adds first-class type checks (`isBubbleThing`, `isBubbleList`),

    by-id lookups (`getThingById`, `getThingsById`), and async iteration on

    `BubbleList`.


    This OpenAPI document describes the SDK surface as a virtual REST API for

    catalog and discovery purposes. Each "endpoint" represents a callable

    JavaScript function in the plugin runtime; `paths` carry the function name

    and `requestBody`/`responses` describe its parameters and return value.

    '
  version: '4.0'
  contact:
    name: Bubble Support
    url: https://bubble.io/contact
  license:
    name: Bubble Plugin Marketplace Terms
    url: https://bubble.io/legal/plugins
servers:
- url: virtual://plugin-runtime
  description: 'Virtual server. Plugin actions and elements execute inside the Bubble

    runtime; there is no public HTTP endpoint.

    '
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:
    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).'
    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
    ActionProperties:
      type: object
      description: Map of property names to values, defined by the plugin author in the editor.
      additionalProperties: true