API and Extension Surfaces
Buzzy has several ways to read data, change data, run custom logic, and expose an app to external tools. They are related, but they are not interchangeable.
The main overlap is the app definition and permission model. REST API, Async API, Node.js client, Buzzy Functions, code widgets, and Custom MCP all work against the same Buzzy apps, datatables, rows, fields, users, teams, and access rules. The difference is where the code runs, who calls it, and what kind of experience you are building.
Quick Comparison
Custom UI inside a Buzzy screen, such as maps, charts, dashboards, rich filters, booking panels, or file managers
Browser/webview sandbox inside the Buzzy app
The signed-in app user interacting with a screen
Uses the current app/user/screen/row context
The UI container. Use the Async API inside it when it needs Buzzy data or actions.
Reading/updating Buzzy data from a code widget, navigating screens, shared widget state, running app functions
Inside a code widget iframe
Code running in that widget
Follows server-side row access, Field view/edit, and Private Data rules for the current user
Similar row semantics to REST, but scoped to the in-app widget context.
External systems reading or updating Buzzy app data over HTTP
Outside Buzzy, over HTTPS
External service, script, backend, integration, or test runner
Authenticated Buzzy user/integration account; server-side permissions still apply
Canonical docs for shared row semantics, metadata, embeddingRowID, and datatable CRUD payloads.
Node.js apps and scripts that need easier REST API calls
Node.js process outside Buzzy, or bundled into server-side code
Node app, CLI, backend service, Lambda with dependencies bundled
Same as REST API
Convenience wrapper around REST, not a separate permission model.
Server-side logic, external APIs, AI calls, webhooks, sensitive processing, scheduled/background logic
Buzzy-managed AWS Lambda runtime
Buzzy screen action, code widget, integration, or sometimes MCP tool exposure
Function caller and function implementation both matter; keep secrets in Constants
Use when code needs secrets, privileged logic, provider calls, or server-side execution.
Exposing an existing Buzzy app as tools to ChatGPT, Claude, or another MCP client
MCP client calls Buzzy-hosted app tools
AI assistant acting for an authenticated Buzzy user
OAuth/user-authenticated tools; same row, field, and Private Data rules
App-specific alternative to direct REST/API integration when an assistant should use governed CRUD tools and available functions.
How They Relate
Same App Model
All surfaces work with the same underlying Buzzy app model:
apps
datatables
fields
rows
child file/image records
users, teams, and organizations
screen and row context where applicable
row access, Field view, Field edit, and Private Data rules
This means a denied user should not receive raw data just because they use an API surface instead of a screen.
REST is the Canonical Data Reference
Use the REST docs as the canonical reference for shared row and payload semantics:
The Async API and Node.js client intentionally share many of these concepts. The Async API adds in-app widget context. The Node.js client adds convenience methods over REST.
Code Widgets and Async API Are Paired
A code widget is the place where custom browser-side UI runs. The Async API is the bridge that lets that custom UI interact with Buzzy.
Use this pair when you need:
a custom search/filter panel
a map or chart
a gallery or file manager
a booking panel
a dashboard with richer controls
widget-to-widget shared state
current row or current screen context
Do not put API keys or sensitive provider calls directly in widget code. Use a Buzzy Function for that.
Functions Are the Server-Side Boundary
Buzzy Functions are the right boundary for:
external API calls
AI provider calls
webhooks
secret handling
sensitive transformations
privileged business logic
operations that should not run in the browser
Functions can be called from screens, actions, and code widgets. They can also be part of an app's Custom MCP tool surface when exposed that way.
Use Constants for API keys, base URLs, model names, and other reusable configuration. Do not hardcode secrets in widgets, functions, samples, or docs.
Custom MCP is Assistant-Facing
Buzzy Custom MCP is for an app that already exists. It exposes app-specific tools to MCP clients such as ChatGPT or Claude.
Use Custom MCP when:
an assistant should list, get, create, update, or delete app records through governed tools
the app should expose selected Buzzy Functions as tools
users should authenticate through Buzzy and keep the app's existing access model
you want an assistant-facing tool layer rather than a custom REST integration
For example, an MCP client could let Claude or ChatGPT shortlist Short Stays properties, create a booking enquiry, update care coordination tasks, summarize compliance findings, or reschedule field service jobs. Each example still operates through the enabled app's datatables, fields, functions, and permissions.
Do not treat Custom MCP as a new-app build path. Use Buzzy Builder MCP when the assistant should build or edit the app definition.
Choosing the Right Surface
Build a custom interactive UI inside a screen
Code widget
Let that widget read rows, update rows, navigate, share state, or call app functions
Async API / BuzzyFrameAPI
Let an external system integrate over HTTP
REST API
Write a Node.js integration without hand-coding every HTTP request
Node.js API client
Call Stripe, OpenAI, Anthropic, SendGrid, weather APIs, or another external service securely
Buzzy Function + Constants
Run custom server-side business logic from a Buzzy action
Buzzy Function
Expose app CRUD and functions to ChatGPT, Claude, or another MCP client
Buzzy Custom MCP
Let an AI agent create, inspect, adapt, or edit the app itself
Buzzy Builder MCP
Common Architectures
Code widget + Async API
A map widget reads location rows, filters a Buzzy view, and updates shared screen state.
Code widget + Buzzy Function
A booking panel collects inputs, then calls a server-side eligibility or pricing function.
Buzzy Function + Constants
A support app sends a ticket summary to an AI provider using encrypted provider keys.
REST API + Node.js client
A nightly integration syncs approved rows into an external reporting database.
Custom MCP + Functions
Claude can query approved app records and trigger a safe server-side workflow exposed as a Buzzy Function tool.
Builder MCP + Code widget + Function
An AI coding agent inspects the app, adds a custom dashboard widget, creates the supporting function, wires the screen, and verifies it.
Security Checklist
Authenticate as the user or integration account that should have access.
Test both allowed and denied users.
Keep secrets in Constants.
Use Functions for provider calls and sensitive logic.
Do not rely on hidden UI as a security boundary.
Confirm row access, Field view, Field edit, and Private Data behavior on every surface you expose.
Run Security Review before exposing sensitive data through REST, Async API, Custom MCP, functions, or code widgets.
Related Pages
Last updated