Bubble Element API

openapi: 3.2.0
info:
  title: Bubble Plugin Element 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: Element
  description: Visual element lifecycle hooks invoked by the Bubble page renderer.
paths:
  /elements/{elementName}/initialize:
    post:
      tags:
      - Element
      summary: Initialize Element
      description: 'Element initialize hook. Receives `(instance, context)`. Use to set up

        DOM state, allocate resources, and register state.

        '
      operationId: initializeElement
      parameters:
      - name: elementName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                instance:
                  $ref: '#/components/schemas/ElementInstance'
                context:
                  $ref: '#/components/schemas/ClientContext'
      responses:
        '200':
          description: Initialization complete.
  /elements/{elementName}/update:
    post:
      tags:
      - Element
      summary: Update Element
      description: 'Element update hook. Receives `(instance, properties, context)`.

        Triggered when any of the element''s bound properties change.

        '
      operationId: updateElement
      parameters:
      - name: elementName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                instance:
                  $ref: '#/components/schemas/ElementInstance'
                properties:
                  $ref: '#/components/schemas/ActionProperties'
                context:
                  $ref: '#/components/schemas/ClientContext'
      responses:
        '200':
          description: Update applied.
components:
  schemas:
    ElementInstance:
      type: object
      description: Element instance handle for setting state, publishing values, and triggering events.
      additionalProperties: true
    ActionProperties:
      type: object
      description: Map of property names to values, defined by the plugin author in the editor.
      additionalProperties: true
    ClientContext:
      type: object
      description: Client-side context passed to actions and element hooks.
      additionalProperties: true