bubblio-dev Platform Sync API

openapi: 3.2.0
info:
  title: Bubblio Dev Platform Sync API
  version: 1.0.0
  contact:
    email: bubblio@andresio.com
  description: 'Operations tagged platform-sync across 2 of this provider''s published API definitions: openapi.yaml, bubblio-dev-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.bubblio.dev
  description: Hosted production platform — the canonical host.
- url: https://andresomar95--bubblio-api-serve.modal.run
  description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
tags:
- name: platform-sync
  description: The code-declared action registry sync (shapes only, never policy).
paths:
  /v1/agent-door/actions/sync:
    post:
      tags:
      - platform-sync
      summary: Push code-declared action shapes (the SDK's door.sync)
      description: 'SHAPES ONLY, never capability: synced actions always arrive with policy `off`, and

        `suggestedPolicy`/`approvalSuggestion` are displayed next to the dashboard control,

        never applied — which is exactly why API-key auth is allowed here. Idempotent;

        actions no longer declared are ORPHANED (flagged, never deleted); destructive-

        looking NAMES sync anyway with the suggestion dropped and a warning returned

        (machine callers must not 400 on a heuristic). Declaring `connectPath` sets the

        phone-connect page; `payments` sets the rails profile (PUBLISHABLE key only —

        sk_/rk_ values are refused by name); omitting either clears it.'
      operationId: syncDoorActions
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - callbackUrl
              - actions
              properties:
                callbackUrl:
                  type: string
                  format: uri
                  description: https (http for localhost only).
                connectPath:
                  type: string
                  description: Path on the platform site, resolved against callbackUrl.
                payments:
                  type: object
                  properties:
                    rails:
                      type: array
                      items:
                        type: string
                        enum:
                        - payment_link
                        - stripe_spt
                    stripePublishableKey:
                      type: string
                      description: pk_… only.
                actions:
                  type: array
                  items:
                    type: object
                    required:
                    - name
                    - description
                    - parameters
                    properties:
                      name:
                        type: string
                        maxLength: 64
                      description:
                        type: string
                      parameters:
                        type: object
                        description: JSON Schema (object/properties/required).
                      suggestedPolicy:
                        type: string
                        enum:
                        - 'off'
                        - keyed
                        - any
                      approvalSuggestion:
                        type: string
                        enum:
                        - auto
                        - mandate
                        - always
                      price:
                        type: object
                        properties:
                          amount_cents:
                            type: integer
                            minimum: 1
                          currency:
                            type: string
                            const: usd
                      timeoutSeconds:
                        type: integer
      responses:
        '200':
          description: The sync result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  synced:
                    type: integer
                  orphaned:
                    type: integer
                  unchanged:
                    type: integer
                  pendingDecision:
                    type: integer
                  warnings:
                    type: array
                    items:
                      type: string
        '400':
          $ref: '#/components/responses/CalmBadRequest'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
components:
  responses:
    CalmBadRequest:
      description: One calm sentence naming the malformed field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CalmError'
  schemas:
    CalmError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        code:
          type: string
          description: Machine-readable refusal code, present where documented — branch on this, never on message text.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: The platform's Bubblio API key (`bbl_…`). Server-side only.
    consentToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The human's passkey-session token from `POST /approvals/session`.
x-refined-from:
- openapi.yaml
- bubblio-dev-openapi.yaml