> 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/buzzy-rest-api/rest-api/endpoint-parameter-guide.md). # 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: ```http X-Auth-Token: X-User-Id: 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: ```json { "microAppID": "", "searchFilter": [ { "resourceID": "", "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.