Bubble · Capability
Bubble Headless Backend
Use a Bubble app as a headless backend for an external mobile or web client. Combines the Data API for CRUD plus the Workflow API for business logic into a single capability that exposes a unified REST surface and an MCP tool surface.
What You Can Do
GET
List records
— List records of a type
/records/{typename}
POST
Create record
— Create a new record
/records/{typename}
GET
Get record
— Get a record by id
/records/{typename}/{uid}
PATCH
Modify record
— Patch a record
/records/{typename}/{uid}
DELETE
Delete record
— Delete a record
/records/{typename}/{uid}
POST
Trigger workflow
— Trigger a backend workflow
/workflows/{workflow_name}
MCP Tools
search-records
Search records of a Bubble data type with constraints
read-only
get-record
Get a Bubble record by id
read-only
create-record
Create a new Bubble record
modify-record
Patch an existing Bubble record
delete-record
Delete a Bubble record
trigger-workflow
Trigger a Bubble backend workflow by name
Capability Spec
naftiko: 1.0.0-alpha2
info:
label: Bubble Headless Backend
description: Use a Bubble app as a headless backend for an external mobile or web client. Combines the Data API for CRUD plus the Workflow API for business logic into a single capability that exposes a unified REST surface and an MCP tool surface.
tags:
- Bubble
- Headless
- No-Code
- Backend
- Integration
created: '2026-05-06'
modified: '2026-05-06'
binds:
- namespace: env
keys:
BUBBLE_API_TOKEN: BUBBLE_API_TOKEN
BUBBLE_APP_NAME: BUBBLE_APP_NAME
capability:
consumes:
- type: http
namespace: bubble-data
baseUri: https://{{BUBBLE_APP_NAME}}.bubbleapps.io/api/1.1
description: Bubble Data API for CRUD against the app database
authentication:
type: bearer
token: '{{BUBBLE_API_TOKEN}}'
resources:
- name: things
path: /obj/{typename}
description: Records of a data type
operations:
- name: search-things
method: GET
description: Search records of a data type
inputParameters:
- name: typename
in: path
type: string
required: true
description: Lowercase data type name
- name: constraints
in: query
type: string
required: false
description: JSON-encoded constraints
- name: cursor
in: query
type: integer
required: false
description: Pagination cursor
- name: limit
in: query
type: integer
required: false
description: Page size
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
- name: create-thing
method: POST
description: Create a record
inputParameters:
- name: typename
in: path
type: string
required: true
description: Lowercase data type name
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
- name: thing
path: /obj/{typename}/{uid}
description: Single record operations
operations:
- name: get-thing
method: GET
description: Get a record by id
inputParameters:
- name: typename
in: path
type: string
required: true
description: Lowercase data type name
- name: uid
in: path
type: string
required: true
description: Unique record id
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
- name: modify-thing
method: PATCH
description: Patch a record
inputParameters:
- name: typename
in: path
type: string
required: true
description: Lowercase data type name
- name: uid
in: path
type: string
required: true
description: Unique record id
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
- name: delete-thing
method: DELETE
description: Delete a record
inputParameters:
- name: typename
in: path
type: string
required: true
description: Lowercase data type name
- name: uid
in: path
type: string
required: true
description: Unique record id
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
- type: http
namespace: bubble-workflow
baseUri: https://{{BUBBLE_APP_NAME}}.bubbleapps.io/api/1.1
description: Bubble Workflow API for backend business logic
authentication:
type: bearer
token: '{{BUBBLE_API_TOKEN}}'
resources:
- name: workflow
path: /wf/{workflow_name}
description: Trigger a workflow by name
operations:
- name: trigger-workflow
method: POST
description: Invoke a backend workflow with JSON parameters
inputParameters:
- name: workflow_name
in: path
type: string
required: true
description: Workflow slug
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
exposes:
- type: rest
port: 8080
namespace: bubble-headless-api
description: Unified REST API for the Bubble headless backend
resources:
- path: /records/{typename}
name: records
description: Records of a data type
operations:
- method: GET
name: list-records
description: List records of a type
call: bubble-data.search-things
with:
typename: rest.typename
outputParameters:
- type: object
mapping: $.
- method: POST
name: create-record
description: Create a new record
call: bubble-data.create-thing
with:
typename: rest.typename
outputParameters:
- type: object
mapping: $.
- path: /records/{typename}/{uid}
name: record
description: Individual record
operations:
- method: GET
name: get-record
description: Get a record by id
call: bubble-data.get-thing
with:
typename: rest.typename
uid: rest.uid
outputParameters:
- type: object
mapping: $.
- method: PATCH
name: modify-record
description: Patch a record
call: bubble-data.modify-thing
with:
typename: rest.typename
uid: rest.uid
outputParameters:
- type: object
mapping: $.
- method: DELETE
name: delete-record
description: Delete a record
call: bubble-data.delete-thing
with:
typename: rest.typename
uid: rest.uid
outputParameters:
- type: object
mapping: $.
- path: /workflows/{workflow_name}
name: workflows
description: Trigger workflows
operations:
- method: POST
name: trigger-workflow
description: Trigger a backend workflow
call: bubble-workflow.trigger-workflow
with:
workflow_name: rest.workflow_name
outputParameters:
- type: object
mapping: $.
- type: mcp
port: 9080
namespace: bubble-headless-mcp
transport: http
description: MCP server enabling AI agents to operate a Bubble app as a headless backend.
tools:
- name: search-records
description: Search records of a Bubble data type with constraints
hints:
readOnly: true
openWorld: false
call: bubble-data.search-things
with:
typename: tools.typename
outputParameters:
- type: object
mapping: $.
- name: get-record
description: Get a Bubble record by id
hints:
readOnly: true
call: bubble-data.get-thing
with:
typename: tools.typename
uid: tools.uid
outputParameters:
- type: object
mapping: $.
- name: create-record
description: Create a new Bubble record
hints:
readOnly: false
destructive: false
call: bubble-data.create-thing
with:
typename: tools.typename
outputParameters:
- type: object
mapping: $.
- name: modify-record
description: Patch an existing Bubble record
hints:
readOnly: false
destructive: false
call: bubble-data.modify-thing
with:
typename: tools.typename
uid: tools.uid
outputParameters:
- type: object
mapping: $.
- name: delete-record
description: Delete a Bubble record
hints:
readOnly: false
destructive: true
call: bubble-data.delete-thing
with:
typename: tools.typename
uid: tools.uid
outputParameters:
- type: object
mapping: $.
- name: trigger-workflow
description: Trigger a Bubble backend workflow by name
hints:
readOnly: false
destructive: false
call: bubble-workflow.trigger-workflow
with:
workflow_name: tools.workflow_name
outputParameters:
- type: object
mapping: $.