Endpoint Parameter Guide

This page is the quick parameter reference for Buzzy REST endpoints. Endpoint-specific pages still contain examples, but this guide lists the required inputs, optional inputs, and the main caveats for each REST endpoint.

Common Request Rules

Most endpoints use JSON over POST.

Authenticated endpoints require these headers:

X-Auth-Token: <authToken from /api/login>
X-User-Id: <userId from /api/login>
Content-Type: application/json

Some endpoints also require x-api-key. If both token auth and API-key auth are documented for an endpoint, use both unless the endpoint page explicitly says otherwise.

Best practices:

• Always use IDs from the Buzzy editor or API responses, not display names, for microAppID, rowID, fieldID, organizationID, teamID, and teamMemberID.

• Treat microAppID as the Datatable resource ID. The historical endpoint names still use microapp.

• Use POST /api/login first and keep authToken and userId out of logs and screenshots.

• Send numbers as numbers when possible. Older examples may show quoted skip or limit; prefer numeric values.

• For Datatable paging, use explicit limit and skip on the row-query object. Do not rely on implicit defaults.

Authentication

Endpoint	Method	Required parameters	Optional parameters	Notes
/api/login	POST	email, password	none	Returns authToken and userId. Use these values in X-Auth-Token and X-User-Id.
/api/logout	POST	auth headers	none	Invalidates the current auth token.
/api/userid	GET	email query parameter	none	Returns a user ID for a known email address. Requires the endpoint to be enabled and authorized in the target environment.

Datatable Read Operations

Endpoint	Method	Required parameters	Optional parameters	Notes
/api/microappdata	POST	microAppID	searchFilter, optSearchFilters, optViewFilters, optViewSort, optLimit, optIsVectorSearch, optVectorSearchString, optVectorSearchNumCandidates, buzzyFormat, resultContentType, optIsStatic, optExcludeMicroApps	Read many rows. Use searchFilter: [{ resourceID: microAppID, limit, skip }] for paging. Use optViewSort with raw sort fields such as { "sortVal": 1 } when you know the stored sort field.
/api/microappdata/row	POST	rowID	none	Read exactly one row by ID. Use this when the row is already known instead of filtering a collection.

/api/microappdata paging and sorting:

{
  "microAppID": "<datatable id>",
  "searchFilter": [
    {
      "resourceID": "<datatable id>",
      "limit": 20,
      "skip": 40
    }
  ],
  "optViewSort": {
    "sortVal": 1
  }
}

Best practices:

• Always include both limit and skip for paged reads.

• Use a stable sort when paging. Without a stable sort, rows inserted at similar times can move between pages.

• Use embeddingRowID in optViewFilters when reading child rows for a parent row.

• Keep buzzyFormat as false unless you specifically need raw internal row data.

Datatable Write Operations

Endpoint	Method	Required parameters	Optional parameters	Notes
/api/insertmicroapprow	POST	microAppID, rowData	embeddingRowID, viewers, teamViewers, userID, ignoreActionRules	Insert one row. rowData keys should be Datatable field labels.
/api/insertmicroapprows	POST	microAppID, rows	embeddingRowID, viewers, userID, ignoreActionRules	Batch insert. rows must be a non-empty array. Current maximum is 10,000 rows per request.
/api/updatemicroapprow	POST	rowID, rowData	microAppID, embeddingRowID, userID, ignoreActionRules	Update one row. Viewer and Team Viewer field values belong inside rowData using field labels.
/api/removemicroapprow	POST	rowID	none	Delete one row. This is destructive; confirm the row ID before calling it.

Best practices:

• Use batch insert for imports or sync jobs; use single-row insert for UI-like actions.

• Do not send system metadata such as _id, submitted, or parentResourceID inside rowData.

• Use embeddingRowID when inserting child rows into a sub-table.

• Use ignoreActionRules only for controlled admin or migration flows.

MicroApp Child And File Operations

Endpoint	Method	Required parameters	Optional parameters	Notes
/api/microappchild/list	POST	parent row and field identifiers documented on the endpoint page	none	Lists child file/image records for a row field.
/api/microappchild/create	POST	parent row ID, field ID, child content	none	Creates a child file/image record. Upload the file itself first when needed.
/api/microappchild/update	POST	child ID and update payload	none	Updates child metadata.
/api/microappchild/delete	POST	child ID	none	Deletes a child record.
/api/microappchild/s3copy	POST	source and destination S3/resource details	none	Copies a file between Buzzy-managed S3 locations.
/api/microappchild/uploadFileToS3	POST	file URL, target resource/field details	none	Downloads a file from the URL and uploads it to Buzzy S3.

Best practices:

• Create or identify the parent row before creating child records.

• Store file metadata on the child record and row field value according to the endpoint example.

• Do not use public file URLs for sensitive files unless the app’s storage policy permits it.

AI App Creation

Endpoint	Method	Required parameters	Optional parameters	Notes
/api/createappwithprompt	POST	userEmail, appPrompt	attachments	Starts app generation asynchronously. Treat a successful response as kickoff accepted, then poll status.
/api/createappwithprompt/status	POST	appID	none	Returns generation status for an app created through the prompt endpoint.

Best practices:

• Authenticate first with /api/login.

• Record the returned editor URL or appID.

• Poll status and then verify persisted resources rather than relying only on UI progress text.

Notifications

Endpoint	Method	Required parameters	Optional parameters	Notes
/api/sendnotification	POST	target user/email, app/resource context, message fields documented on the endpoint page	delivery options such as push-only, in-app-only, or badge-only modes	Requires the authenticated user to be allowed to edit the target app.

Best practices:

• Keep notification content short and user-visible.

• Do not include passwords, auth tokens, or private data in notification text.

• Use delivery-mode options intentionally; push-only skips the in-app notification record.

Organizations, Teams, And Members

Endpoint	Method	Required parameters	Optional parameters	Notes
/api/insertorganization	POST	organization fields documented on the endpoint page	none	Creates an organization.
/api/readorganization	POST	organizationID	none	Reads one organization.
/api/updateorganization	POST	organizationID and update fields	none	Updates organization fields.
/api/deleteorganization	POST	organizationID	none	Deletes an organization. Confirm dependencies first.
/api/insertteam	POST	team name and organizationID	description or other documented fields	Creates a team inside an organization.
/api/readteam	POST	teamID	none	Reads one team.
/api/updateteam	POST	teamID and update fields	none	Updates team fields.
/api/deleteteam	POST	teamID	none	Deletes a team. Confirm memberships first.
/api/insertteammembers	POST	teamID, member list	role fields documented on the endpoint page	Adds members to a team.
/api/teammembers	POST	teamID or team IDs documented on the endpoint page	none	Lists team members.
/api/readteammember	POST	teamMemberID	none	Reads one team member record.
/api/updateteammember	POST	teamMemberID, role/update fields	none	Only supported member fields can be changed.
/api/deleteteammember	POST	teamMemberID	none	Removes a member record.
/api/enforceteammembership	POST	organization/team/user membership details documented on the endpoint page	none	Use for controlled membership enforcement flows.

Best practices:

• Prefer IDs from read responses over copied display names.

• Confirm destructive operations before deleting organizations, teams, or memberships.

• Keep membership changes auditable by recording the requesting user and target IDs in your integration logs, without logging auth tokens.