> For the complete documentation index, see [llms.txt](https://docs.buzzy.buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buzzy.buzz/developing-and-extending-buzzy/api-and-extension-surfaces.md). # 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 | Surface | Best for | Runs where | Typical caller | Access model | Notes | | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | [Code widget](/the-building-blocks/code-widget-custom-code.md) | 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. | | [Async API / BuzzyFrameAPI](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components.md) | 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. | | [Buzzy REST API](/developing-and-extending-buzzy/buzzy-rest-api/rest-api.md) | 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 API client](/developing-and-extending-buzzy/buzzy-rest-api/nodejs-api-client.md) | 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. | | [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants.md) | 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. | | [Buzzy Custom MCP](/the-building-blocks/mcp/buzzy-custom-mcp.md) | 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: * [Row Metadata and Relationships](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/row-metadata-and-relationships.md) * [microappdata](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappdata.md) * [microappdata/row](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row.md) * [microappchild](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappchild.md) * [Common API Examples](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/common-api-examples.md) 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](/the-building-blocks/mcp/buzzy-builder-mcp.md) when the assistant should build or edit the app definition. ## Choosing the Right Surface | If you need to... | Use | | -------------------------------------------------------------------------------------------- | -------------------------- | | 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 | Architecture | Example | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | 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](/the-building-blocks/security-review.md) before exposing sensitive data through REST, Async API, Custom MCP, functions, or code widgets. ## Related Pages * [Code widget](/the-building-blocks/code-widget-custom-code.md) * [Async API + React HTML Components](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components.md) * [Buzzy REST API](/developing-and-extending-buzzy/buzzy-rest-api/rest-api.md) * [Node.js API Client](/developing-and-extending-buzzy/buzzy-rest-api/nodejs-api-client.md) * [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants.md) * [Buzzy Custom MCP](/the-building-blocks/mcp/buzzy-custom-mcp.md) * [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp.md)